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.
Install
Section titled “Install”npx shadcn@latest add @0xui/use-token-listpnpm dlx shadcn@latest add @0xui/use-token-listyarn dlx shadcn@latest add @0xui/use-token-listbunx --bun shadcn@latest add @0xui/use-token-listLoad a list
Section titled “Load a 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, ornullfor 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.
Several lists
Section titled “Several lists”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.
Allowlist and blocklist
Section titled “Allowlist and blocklist”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.
The token shape
Section titled “The token shape”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.
Big lists
Section titled “Big lists”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.
Without the hook
Section titled “Without the hook”import { fetchTokenList, parseTokenList, mergeTokenLists } from "@/lib/token-list";
const list = await fetchTokenList("https://tokens.uniswap.org"); // validated and cleanedconst fromFile = parseTokenList(await import("./my-list.json"));