Skip to content

Getting started

Token lists

0xui uses the token list standard, the format of Uniswap's lists. Load any list with useTokenList.

Every 0xui component that takes tokens (Token Select, Token Input, Swap, Send, Portfolio) takes them in the token list standard. It’s the JSON format Uniswap created, and CoinGecko, most DEXs and most wallets publish lists in it. So you don’t map anything: load a list and pass its tokens.

The demos in these docs use Uniswap Labs’ default list, fetched live: about 1,800 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon and more.

Terminal window
npx shadcn@latest add @0xui/use-token-list
import { useTokenList } from "@/hooks/use-token-list";
import { UNISWAP_DEFAULT_LIST } from "@/lib/token-list";
import { TokenSelect } from "@/components/token-select";
function Picker() {
const { tokens, isLoading } = useTokenList(UNISWAP_DEFAULT_LIST);
const [token, setToken] = useState<TokenInfo>();
return <TokenSelect tokens={tokens} isLoading={isLoading} value={token} onValueChange={setToken} />;
}

useTokenList:

  • downloads the list once per session (cached with TanStack Query, one retry);
  • keeps only tokens on the current chain (or chainId, or null for all chains);
  • puts the chain’s native currency first. Lists don’t include it (Uniswap’s has WETH, not ETH), so it’s added from your wagmi chain config with the address NATIVE_TOKEN_ADDRESS (0xEeee…EEeE);
  • drops entries that aren’t EVM tokens. Uniswap’s list includes Solana tokens, for example.
const { tokens } = useTokenList(
[UNISWAP_DEFAULT_LIST, "https://tokens.coingecko.com/base/all.json"],
{ extraTokens: importedTokens }
);

Earlier lists win when two lists contain the same token, and extraTokens win over everything. ipfs:// and ar:// list URLs work too.

Long lists include tokens you may not want to offer. Pass an allowlist (a whitelist) to show only the tokens you support, or a blocklist to hide known scams:

const { tokens } = useTokenList(UNISWAP_DEFAULT_LIST, {
allowlist: [USDC, USDT, WETH, WBTC], // only these, on any chain
blocklist: ["8453:0x…"], // never this one, on Base
});

Entries are token addresses, or chainId:address to pin a chain. Symbols aren’t accepted, because spam tokens copy the symbols of real ones. The blocklist wins when a token is on both, and the native currency is always kept. For plain arrays, use applyTokenFilters(tokens, { allowlist, blocklist }) from @/lib/token-list.

type TokenInfo = {
chainId: number;
address: Address; // checksummed
name: string;
symbol: string;
decimals: number;
logoURI?: string; // https://, ipfs:// or ar://
tags?: string[];
extensions?: {
bridgeInfo?: Record<string, { tokenAddress: Address }>; // Uniswap: the same token on other chains
[key: string]: unknown;
};
};

Writing tokens by hand? Use the same shape. nativeToken(chain) builds the native-currency entry.

Token Icon shows logoURI and resolves ipfs:// through a gateway. When a logo fails to load, which happens often with list logos, it falls back to the built-in icon for the symbol, then to the symbol’s first letters.

Uniswap’s list has about 400 tokens on Ethereum alone, so the components are built for that:

  • Token Select pages through the list 50 rows at a time (tokens you hold first), loading more as you scroll.
  • Balances for the whole list are read in batched multicalls.
  • Portfolio reads every token on the chain and shows 10 rows per page.
import { fetchTokenList, parseTokenList, mergeTokenLists } from "@/lib/token-list";
const list = await fetchTokenList("https://tokens.uniswap.org"); // validated and cleaned
const fromFile = parseTokenList(await import("./my-list.json"));