# Token

Shows which token an amount is in, and opens a picker to change it.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Token.tsx)

Figma: [Elements/Token](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-1266)

## Overview

A token renders a pill with a [TokenLogo](/docs/components/token-logo) and the token's symbol. By default it is a button with a chevron that opens a token picker. Set `readOnly` for a static pill.

## Examples

### Basic

```tsx
import { Token, TokenLogo } from '@tempoxyz/ds'

export function Demo() {
  return (
    <TokenLogo.Provider>
      <Token address="0x20c0000000000000000000000000000000000000" symbol="pathUSD" />
    </TokenLogo.Provider>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Token/Basic.tsx)

### Read-Only

Set `readOnly` to render a span without the chevron, for reviews and receipts.

```tsx
import { Token, TokenLogo } from '@tempoxyz/ds'

export function Demo() {
  return (
    <TokenLogo.Provider>
      <Token address="0x20c0000000000000000000000000000000000000" readOnly symbol="pathUSD" />
    </TokenLogo.Provider>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Token/ReadOnly.tsx)

### Picker

Pass the token to a trigger's `render`, such as a [Dialog](/docs/components/dialog) trigger, to open a token picker.

```tsx
import { Dialog, style, Token, TokenLogo } from '@tempoxyz/ds'
import { useState } from 'react'

const tokens = [
  ['pathUSD', '0x20c0000000000000000000000000000000000000'],
  ['USDC.e', '0x20c000000000000000000000b9537d11c60e8b50'],
  ['USDT0', '0x20c00000000000000000000014f22ca97301eb73'],
] as const

export function Demo() {
  const [selected, setSelected] = useState<(typeof tokens)[number]>(tokens[0])

  return (
    <TokenLogo.Provider>
      <Dialog.Root>
        <Dialog.Trigger render={<Token address={selected[1]} symbol={selected[0]} />} />
        <Dialog.Popup closeButton>
          <Dialog.Header>
            <Dialog.Title>Select token</Dialog.Title>
          </Dialog.Header>
          <Dialog.Body>
            <div {...styles.list()}>
              {tokens.map((token) => (
                <Dialog.Close
                  key={token[1]}
                  onClick={() => setSelected(token)}
                  render={<button type="button" {...styles.option()} />}
                >
                  <TokenLogo address={token[1]} size="large" />
                  {token[0]}
                </Dialog.Close>
              ))}
            </div>
          </Dialog.Body>
        </Dialog.Popup>
      </Dialog.Root>
    </TokenLogo.Provider>
  )
}

namespace styles {
  export const list = style({ display: 'grid', gap: '4' })

  export const option = style({
    alignItems: 'center',
    backgroundColor: 'transparent !custom',
    border: 'none !custom',
    borderRadius: 'xs',
    color: 'content.primary',
    cursor: 'pointer',
    display: 'flex',
    gap: '12',
    padding: '12',
    textAlign: 'start',
    typography: 'body.b2Strong',
    selectors: { '&:hover': { backgroundColor: 'container.regular' } },
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Token/Picker.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Token } from '@tempoxyz/ds'

<Token />
```

## Guidelines

### When to Use

* Name the token after the digits in an [AmountInput](/docs/components/amount-input), and let a person change it.
* Name a fixed token in a review or a receipt with `readOnly`.

### When Not to Use

* Use [TokenLogo](/docs/components/token-logo) for a logo beside a symbol in a list row.
* Use [AssetChip](/docs/components/asset-chip) to list the assets a row supports.
* Use [Select](/docs/components/select) to choose a token in a form field with a label.

### Show the Chevron Only on a Picker

The chevron tells people that the token opens a picker.

**Do:** Set `readOnly` in reviews and receipts, where the token can't change.

```tsx
/**
 * Do example for "Show the Chevron Only on a Picker" on the Token page.
 * Render a read-only pill where the token can't change.
 * @module
 */
import { style, Token, TokenLogo } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <TokenLogo.Provider>
      <div {...styles.row()}>
        <span {...styles.amount()}>25.00</span>
        <Token address="0x20c0000000000000000000000000000000000000" readOnly symbol="pathUSD" />
      </div>
    </TokenLogo.Provider>
  )
}

namespace styles {
  export const amount = style({ color: 'content.primary', typography: 'heading.h2' })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

**Don't:** Show the chevron on a token that opens nothing.

```tsx
/**
 * Don't example for "Show the Chevron Only on a Picker" on the Token page.
 * A chevron on a token that can't change promises a picker that never opens.
 * @module
 */
import { style, Token, TokenLogo } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <TokenLogo.Provider>
      <div {...styles.row()}>
        <span {...styles.amount()}>25.00</span>
        <Token address="0x20c0000000000000000000000000000000000000" symbol="pathUSD" />
      </div>
    </TokenLogo.Provider>
  )
}

namespace styles {
  export const amount = style({ color: 'content.primary', typography: 'heading.h2' })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

### Prefer the Address

* **Address (address):** Loads the logo directly. `symbol` still labels the pill.
* **Symbol (symbol):** Resolves the logo through the token list first.

## Content

### Use the Token's Symbol

Write the symbol as the token defines it, such as pathUSD or USDC.e. Keep amounts, network names, and verbs outside the pill.

## Accessibility

A token renders a native `<button>` built on Base UI Button, or a `<span>` when `readOnly`. The logo and the chevron are hidden from screen readers.

### Semantics

* **Root (button):** The symbol names the button. A picker trigger adds popup state.
* **Read-Only (readOnly):** Renders a span, so screen readers read the symbol as text.

### Keyboard

* **Move Focus to the Token (Tab):** Moves focus to the token.
* **Open the Picker (Enter or Space):** Opens the picker that the token triggers.

### Your Responsibilities

* **Open a Picker (render):** Pass the token to a picker trigger's `render`. If nothing opens, set `readOnly`.
* **Describe the Action (aria-label):** If the symbol alone doesn't say what the token does, add a label that keeps the symbol.

## Related

[TokenLogo](/docs/components/token-logo)

Use for token logos.

[AmountInput](/docs/components/amount-input)

Use for entering an amount beside a token.

[AssetChip](/docs/components/asset-chip)

Use for listing the assets a row supports.

[Dialog](/docs/components/dialog)

Use for a token picker.
