# Token Select

> Searchable token picker with recent and popular tokens and the user's balances.

- Install: `npx shadcn@latest add @0xui/token-select`
- Registry JSON: https://0xui.io/r/token-select.json
- Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/token-select.tsx

A token pill that opens a picker. It has search by symbol, name or pasted address, quick picks (your recent tokens, then `popular`), and the full list with tokens you hold sorted first. Arrow keys move between the search field and the rows.

The demo loads [Uniswap's default token list](https://tokens.uniswap.org) live.

## Installation

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

## Usage

Tokens use the [token list standard](https://0xui.io/getting-started/token-lists.md), the format of Uniswap's lists. Load one with `useTokenList`:

```tsx
import { TokenSelect, type Token } from "@/components/token-select";
import { useTokenList } from "@/hooks/use-token-list";
import { UNISWAP_DEFAULT_LIST } from "@/lib/token-list";

const { tokens, isLoading } = useTokenList(UNISWAP_DEFAULT_LIST);
const [token, setToken] = useState<Token>();

<TokenSelect
  tokens={tokens}
  isLoading={isLoading}
  value={token}
  onValueChange={setToken}
  popular={["ETH", "USDC", "WBTC"]}
/>;
```

Only tokens on `chainId` (the current chain by default) are listed. `useTokenList` adds the native currency (ETH) first, since lists don't include it, and takes an `allowlist` or `blocklist` to control which tokens appear.

The list is paged, 50 rows at a time (`pageSize`): more load as the user scrolls, or with "Show more".

Below 640px the picker opens as a bottom drawer. Set `mode` to force a dialog or a drawer. See [Responsive Dialog](https://0xui.io/components/responsive-dialog.md).

> **Tip: In production**
>
> Balances are read over RPC by default: fine for prototypes, but heavy for long lists. With an [index of the chain](https://0xui.io/getting-started/indexed-data.md), pass `balances` and nothing is read over RPC:
>
> ```tsx
> <TokenSelect tokens={tokens} balances={balancesFromYourIndex} … />
> ```

### While the list loads

Pass `isLoading` and the picker shows skeleton rows under the tokens it already has, which is usually just the native currency. This demo's list never arrives:

### Your own trigger

```tsx
<TokenSelectDialog open={open} onOpenChange={setOpen} tokens={tokens} onValueChange={setToken} />
```

### Headless

`filterTokens(tokens, query)` is the search, and `useTokenBalances(tokens)` reads every balance in one batch.

## Props

Also accepts shadcn `Button` props for the trigger.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tokens` | `Token[]` | — | Token list. |
| `value` | `Token` | — | Selected token. |
| `onValueChange` | `(token) => void` | — | Called on pick. The dialog closes itself. |
| `chainId` | `number` | current chain | Chain to list. |
| `popular` | `string[]` | `[]` | Symbols or addresses for quick picks. |
| `showBalances` | `boolean` | `true` | Read and show the connected account's balances. |
| `prices` | `Record<symbol, number>` | — | Sort held tokens by value. Without prices, held tokens keep list order: raw amounts aren't comparable across tokens. |
| `isLoading` | `boolean` | `false` | The list is still downloading. Shows skeleton rows, and "Loading tokens…" for screen readers. |
| `pageSize` | `number` | `50` | Rows per page. More load on scroll or with "Show more". |
| `balances` | `Record<address, bigint>` | — | Balances from your own source. Skips RPC reads. |
| `mode` | `"auto" \| "dialog" \| "drawer"` | `"auto"` | Bottom drawer on small screens, dialog otherwise. Or force one. |
| `placeholder` | `string` | `"Select token"` | Trigger text with nothing selected. |
| `title` | `ReactNode` | `"Select a token"` | Picker title. |

Recent picks are kept in `localStorage` per chain (4 max). If storage is blocked, they're simply not saved.
