# 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](https://tokenlists.org). 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](https://tokens.uniswap.org)**, fetched live: about 1,800 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon and more.

## Install

```bash
npx shadcn@latest add @0xui/use-token-list
```

## Load a list

```tsx
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.

### Several lists

```tsx
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

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:

```tsx
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

```ts
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.

## Logos

[Token Icon](https://0xui.io/components/token-icon.md) 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

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.

> **Tip: In production**
>
> Reading balances for 400 tokens per user over RPC is fine for a prototype but hits public RPC rate limits at scale. We recommend an [index of the chain](https://0xui.io/getting-started/indexed-data.md): your own Postgres + ClickHouse, or a service like Goldsky. Pass its balances to the `balances` prop.

## Without the hook

```ts
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"));
```
