# Select

Opens a list of options for choosing one value.

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

Figma: [Inputs/Select](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5451) (`Select.Trigger`)

## Overview

Select renders a trigger that opens a listbox, for choosing one value from a short list. If the options fit on screen, prefer [ChoiceGroup](/docs/components/choice-group).

## Examples

### Basic

```tsx
import { Field, Select, style } from '@tempoxyz/ds'
import { Coins, Ethereum, Wallet } from '@tempoxyz/ds/icons'
import { useState } from 'react'

const assets = [
  { balance: '1,240.50', icon: <Coins />, label: 'pathUSD', value: 'pathusd' },
  { balance: '845.00', icon: <Ethereum />, label: 'USDC.e', value: 'usdce' },
  { balance: '0.00', icon: <Wallet />, label: 'Tether', value: 'usdt' },
]

const items = Object.fromEntries(assets.map((asset) => [asset.value, asset.label]))

function Example(props: Pick<Select.Trigger.Props, 'disabled' | 'invalid' | 'variant'>) {
  const [value, setValue] = useState<string | null>('pathusd')

  return (
    <Select.Root items={items} onValueChange={setValue} value={value}>
      <Select.Trigger aria-label="Asset" {...props} {...styles.trigger()}>
        <Select.Value placeholder="Select an asset" />
        <Select.Icon />
      </Select.Trigger>
      <Select.Popup>
        {assets.map((asset) => (
          <Select.Item key={asset.value} label={asset.label} value={asset.value}>
            <Select.ItemPrefix>{asset.icon}</Select.ItemPrefix>
            <Select.ItemText>{asset.label}</Select.ItemText>
            <Select.ItemSuffix>{asset.balance}</Select.ItemSuffix>
          </Select.Item>
        ))}
        <Select.Separator />
        <Select.Group>
          <Select.GroupLabel>Coming soon</Select.GroupLabel>
          <Select.Item disabled value="other">
            <Select.ItemText>Other</Select.ItemText>
          </Select.Item>
        </Select.Group>
      </Select.Popup>
    </Select.Root>
  )
}

export function Demo() {
  return (
    <Field.Root>
      <Field.Label>Asset</Field.Label>
      <Example />
    </Field.Root>
  )
}

namespace styles {
  export const trigger = style({ maxWidth: '320px !custom' })
}
```

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

### Variant

Set `variant` on `Select.Trigger` to `default` (default) or `outlined`, which draws a 1px line instead of the fill.

```tsx
import { Field, Select, style } from '@tempoxyz/ds'

const items = { mainnet: 'Tempo', testnet: 'Tempo Testnet' }

export function Demo() {
  return (
    <div {...styles.grid()}>
      {(['default', 'outlined'] as const).map((variant) => (
        <Field.Root key={variant}>
          <Field.Label>Network</Field.Label>
          <Select.Root defaultValue="mainnet" items={items}>
            <Select.Trigger variant={variant}>
              <Select.Value />
              <Select.Icon />
            </Select.Trigger>
            <Select.Popup>
              {Object.entries(items).map(([value, label]) => (
                <Select.Item key={value} label={label} value={value}>
                  <Select.ItemText>{label}</Select.ItemText>
                </Select.Item>
              ))}
            </Select.Popup>
          </Select.Root>
        </Field.Root>
      ))}
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '24',
    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
  })
}
```

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

### Prefix

Put a `Select.Prefix` before `Select.Value` to name what a filter selects, such as By in By Anyone. Name the trigger with `aria-label` too.

```tsx
/**
 * Prefix demo for the Select page: a dashboard filter whose prefix names what it filters.
 * @module
 */
import { Select, style } from '@tempoxyz/ds'

const owners = { anyone: 'Anyone', me: 'Me', team: 'My team' }

/** Renders a filter that hugs its prefix, value, and chevron. */
export function Demo() {
  return (
    <Select.Root defaultValue="anyone" items={owners}>
      <Select.Trigger aria-label="Owner" {...styles.trigger()}>
        <Select.Prefix>By</Select.Prefix>
        <Select.Value />
        <Select.Icon />
      </Select.Trigger>
      <Select.Popup>
        {Object.entries(owners).map(([value, label]) => (
          <Select.Item key={value} label={label} value={value}>
            <Select.ItemText>{label}</Select.ItemText>
          </Select.Item>
        ))}
      </Select.Popup>
    </Select.Root>
  )
}

namespace styles {
  // A filter sizes to its content instead of filling the row.
  export const trigger = style({ width: 'max-content !custom' })
}
```

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

### Field

Wrap the select in a `Field.Root` to label it and describe it.

```tsx
import { Field, Select, style } from '@tempoxyz/ds'
import { Coins, Ethereum, Wallet } from '@tempoxyz/ds/icons'
import { useState } from 'react'

const assets = [
  { balance: '1,240.50', icon: <Coins />, label: 'pathUSD', value: 'pathusd' },
  { balance: '845.00', icon: <Ethereum />, label: 'USDC.e', value: 'usdce' },
  { balance: '0.00', icon: <Wallet />, label: 'Tether', value: 'usdt' },
]

const items = Object.fromEntries(assets.map((asset) => [asset.value, asset.label]))

function Example(props: Pick<Select.Trigger.Props, 'disabled' | 'invalid' | 'variant'>) {
  const [value, setValue] = useState<string | null>('pathusd')

  return (
    <Select.Root items={items} onValueChange={setValue} value={value}>
      <Select.Trigger aria-label="Asset" {...props} {...styles.trigger()}>
        <Select.Value placeholder="Select an asset" />
        <Select.Icon />
      </Select.Trigger>
      <Select.Popup>
        {assets.map((asset) => (
          <Select.Item key={asset.value} label={asset.label} value={asset.value}>
            <Select.ItemPrefix>{asset.icon}</Select.ItemPrefix>
            <Select.ItemText>{asset.label}</Select.ItemText>
            <Select.ItemSuffix>{asset.balance}</Select.ItemSuffix>
          </Select.Item>
        ))}
        <Select.Separator />
        <Select.Group>
          <Select.GroupLabel>Coming soon</Select.GroupLabel>
          <Select.Item disabled value="other">
            <Select.ItemText>Other</Select.ItemText>
          </Select.Item>
        </Select.Group>
      </Select.Popup>
    </Select.Root>
  )
}

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Field.Root>
        <Field.Label>Asset</Field.Label>
        <Example />
        <Field.Description>Pays the network fee.</Field.Description>
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '12',
    gridTemplateColumns: 'repeat(auto-fill, minmax(240px, 1fr)) !custom',
  })

  export const trigger = style({ maxWidth: '320px !custom' })
}
```

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

### Invalid

Set `invalid` on `Select.Trigger` to mark the value as invalid.

```tsx
import { Select, style } from '@tempoxyz/ds'
import { Coins, Ethereum, Wallet } from '@tempoxyz/ds/icons'
import { useState } from 'react'

const assets = [
  { balance: '1,240.50', icon: <Coins />, label: 'pathUSD', value: 'pathusd' },
  { balance: '845.00', icon: <Ethereum />, label: 'USDC.e', value: 'usdce' },
  { balance: '0.00', icon: <Wallet />, label: 'Tether', value: 'usdt' },
]

const items = Object.fromEntries(assets.map((asset) => [asset.value, asset.label]))

function Example(props: Pick<Select.Trigger.Props, 'disabled' | 'invalid' | 'variant'>) {
  const [value, setValue] = useState<string | null>('pathusd')

  return (
    <Select.Root items={items} onValueChange={setValue} value={value}>
      <Select.Trigger aria-label="Asset" {...props} {...styles.trigger()}>
        <Select.Value placeholder="Select an asset" />
        <Select.Icon />
      </Select.Trigger>
      <Select.Popup>
        {assets.map((asset) => (
          <Select.Item key={asset.value} label={asset.label} value={asset.value}>
            <Select.ItemPrefix>{asset.icon}</Select.ItemPrefix>
            <Select.ItemText>{asset.label}</Select.ItemText>
            <Select.ItemSuffix>{asset.balance}</Select.ItemSuffix>
          </Select.Item>
        ))}
        <Select.Separator />
        <Select.Group>
          <Select.GroupLabel>Coming soon</Select.GroupLabel>
          <Select.Item disabled value="other">
            <Select.ItemText>Other</Select.ItemText>
          </Select.Item>
        </Select.Group>
      </Select.Popup>
    </Select.Root>
  )
}

export function Demo() {
  return <Example invalid />
}

namespace styles {
  export const trigger = style({ maxWidth: '320px !custom' })
}
```

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

### Disabled

```tsx
import { Select, style } from '@tempoxyz/ds'
import { Coins, Ethereum, Wallet } from '@tempoxyz/ds/icons'
import { useState } from 'react'

const assets = [
  { balance: '1,240.50', icon: <Coins />, label: 'pathUSD', value: 'pathusd' },
  { balance: '845.00', icon: <Ethereum />, label: 'USDC.e', value: 'usdce' },
  { balance: '0.00', icon: <Wallet />, label: 'Tether', value: 'usdt' },
]

const items = Object.fromEntries(assets.map((asset) => [asset.value, asset.label]))

function Example(props: Pick<Select.Trigger.Props, 'disabled' | 'invalid' | 'variant'>) {
  const [value, setValue] = useState<string | null>('pathusd')

  return (
    <Select.Root items={items} onValueChange={setValue} value={value}>
      <Select.Trigger aria-label="Asset" {...props} {...styles.trigger()}>
        <Select.Value placeholder="Select an asset" />
        <Select.Icon />
      </Select.Trigger>
      <Select.Popup>
        {assets.map((asset) => (
          <Select.Item key={asset.value} label={asset.label} value={asset.value}>
            <Select.ItemPrefix>{asset.icon}</Select.ItemPrefix>
            <Select.ItemText>{asset.label}</Select.ItemText>
            <Select.ItemSuffix>{asset.balance}</Select.ItemSuffix>
          </Select.Item>
        ))}
        <Select.Separator />
        <Select.Group>
          <Select.GroupLabel>Coming soon</Select.GroupLabel>
          <Select.Item disabled value="other">
            <Select.ItemText>Other</Select.ItemText>
          </Select.Item>
        </Select.Group>
      </Select.Popup>
    </Select.Root>
  )
}

export function Demo() {
  return <Example disabled />
}

namespace styles {
  export const trigger = style({ maxWidth: '320px !custom' })
}
```

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

## Anatomy

Import the component and assemble its parts.

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

<Select.Root>
  <Select.Trigger>
    <Select.Prefix />
    <Select.Value />
    <Select.Icon />
  </Select.Trigger>
  <Select.Popup>
    <Select.Item>
      <Select.ItemPrefix />
      <Select.ItemText />
      <Select.ItemSuffix />
    </Select.Item>
    <Select.Separator />
    <Select.Group>
      <Select.GroupLabel />
    </Select.Group>
  </Select.Popup>
</Select.Root>
```

## Guidelines

### When to Use

* Choose one value from more than five scannable options, such as an asset or a network.
* Filter a dashboard or table where space is tight, such as a chart's time range.
* Set `multiple` to pick several values when a [CheckboxGroup](/docs/components/checkbox-group) takes too much room.

### When Not to Use

* Use [RadioGroup](/docs/components/radio-group) for two to five options compared side by side.
* Use [ChoiceGroup](/docs/components/choice-group) for two to four short options that switch a view, such as 1H, 24H, and 7D.
* Use [Combobox](/docs/components/combobox) for a long list filtered by typing, such as every token on Tempo.
* Use [Autocomplete](/docs/components/autocomplete) when any typed text is a valid value.
* Use [Menu](/docs/components/menu) for a list of actions. A select holds a value.

### Show Labels, Not Raw Values

Pass `items` to `Select.Root` to map each value to its label. Without it, `Select.Value` renders the raw value.

**Do:** Pass `items` so the trigger shows the asset's name.

```tsx
/**
 * Do example for "Show Labels, Not Raw Values" on the Select page.
 * Pass `items` so the trigger shows the asset's name.
 * @module
 */
import { Field, Select, style } from '@tempoxyz/ds'

const items = { pathusd: 'pathUSD', usdce: 'USDC.e' }

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Asset</Field.Label>
      <Select.Root defaultValue="usdce" items={items}>
        <Select.Trigger>
          <Select.Value placeholder="Select an asset" />
          <Select.Icon />
        </Select.Trigger>
        <Select.Popup>
          <Select.Item value="pathusd">
            <Select.ItemText>pathUSD</Select.ItemText>
          </Select.Item>
          <Select.Item value="usdce">
            <Select.ItemText>USDC.e</Select.ItemText>
          </Select.Item>
        </Select.Popup>
      </Select.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

**Don't:** Leave the trigger showing an internal value such as `usdce`.

```tsx
/**
 * Don't example for "Show Labels, Not Raw Values" on the Select page.
 * Don't leave the trigger showing an internal value such as `usdce`.
 * @module
 */
import { Field, Select, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Asset</Field.Label>
      <Select.Root defaultValue="usdce">
        <Select.Trigger>
          <Select.Value placeholder="Select an asset" />
          <Select.Icon />
        </Select.Trigger>
        <Select.Popup>
          <Select.Item value="pathusd">
            <Select.ItemText>pathUSD</Select.ItemText>
          </Select.Item>
          <Select.Item value="usdce">
            <Select.ItemText>USDC.e</Select.ItemText>
          </Select.Item>
        </Select.Popup>
      </Select.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

### Order Options Predictably

Pick one ordering rule per list and keep it everywhere the list appears.

* **Numeric or Chronological (smallest first):** For values with a natural order, such as time ranges, sizes, and block heights.
* **Alphabetical (Select.Group):** For tokens, networks, and countries, with the common ones grouped first.
* **Most Used First:** For a few options with one clear favorite first, then the rest in a fixed order.

* Don't reorder options by recent use. People learn positions and typeahead order.
* Split long lists into `Select.Group` sections with a `Select.GroupLabel`, divided by `Select.Separator`.
* Hide options that can never be chosen. Show a `disabled` item only when its group label or text states why, such as Coming soon.

### Choose the Default Deliberately

If one choice suits most people, preselect it with `defaultValue`, such as the largest balance or the last 24 hours. Always give a filter a default.

**Do:** Give a dashboard filter a default that shows data right away.

```tsx
/**
 * Do example for "Choose the Default Deliberately" on the Select page.
 * Give a dashboard filter a default that shows data right away.
 * @module
 */
import { Field, Select, style } from '@tempoxyz/ds'

const items = { '1h': 'Last hour', '24h': 'Last 24 hours', '7d': 'Last 7 days' }

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Time range</Field.Label>
      <Select.Root defaultValue="24h" items={items}>
        <Select.Trigger>
          <Select.Value placeholder="Select a time range" />
          <Select.Icon />
        </Select.Trigger>
        <Select.Popup size="small">
          {Object.entries(items).map(([value, label]) => (
            <Select.Item key={value} value={value}>
              <Select.ItemText>{label}</Select.ItemText>
            </Select.Item>
          ))}
        </Select.Popup>
      </Select.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '12rem !custom' })
}
```

**Don't:** Leave a filter empty with a generic placeholder.

```tsx
/**
 * Don't example for "Choose the Default Deliberately" on the Select page.
 * Don't leave a filter empty with a generic placeholder.
 * @module
 */
import { Field, Select, style } from '@tempoxyz/ds'

const items = { '1h': 'Last hour', '24h': 'Last 24 hours', '7d': 'Last 7 days' }

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Time range</Field.Label>
      <Select.Root items={items}>
        <Select.Trigger>
          <Select.Value placeholder="Select" />
          <Select.Icon />
        </Select.Trigger>
        <Select.Popup size="small">
          {Object.entries(items).map(([value, label]) => (
            <Select.Item key={value} value={value}>
              <Select.ItemText>{label}</Select.ItemText>
            </Select.Item>
          ))}
        </Select.Popup>
      </Select.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '12rem !custom' })
}
```

If a guess could cost something, such as a withdrawal network, leave the select empty. Set a `placeholder` on `Select.Value` that names the choice, such as Select a network, and validate on submit. Add a None option only if none is a valid answer.

### Keep Option Rows Scannable

* **Prefix and suffix:** Put a token icon or [Avatar](/docs/components/avatar) in `Select.ItemPrefix`, and a secondary value such as a balance in `Select.ItemSuffix`.
* **Typeahead label:** If a row holds a prefix or suffix, give `Select.Item` a `label`.
* **Text length:** Keep `Select.ItemText` short. It truncates beside a prefix or suffix.
* **First words:** Start options with distinct words, in a parallel format, such as Last hour and Last 24 hours. Typeahead jumps by first letters.

**Do:** Put the icon and balance in the item's prefix and suffix, and keep the text short.

```tsx
/**
 * Do example for "Keep Option Rows Scannable" on the Select page.
 * Put the icon and balance in the item's prefix and suffix, and keep the text short.
 * @module
 */
import { Check } from '@tempoxyz/ds/icons'
import { style } from '@tempoxyz/ds'
import pathusd from '../../coins/PathUSD.svg'
import usdce from '../../coins/USDCe.svg'
import usdt0 from '../../coins/USDT0.svg'

const assets = [
  { balance: '1,250.00', icon: pathusd, name: 'pathUSD', selected: true },
  { balance: '480.25', icon: usdce, name: 'USDC.e', selected: false },
  { balance: '12.00', icon: usdt0, name: 'USDT0', selected: false },
]

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      {assets.map((asset) => (
        <div key={asset.name} {...styles.item()}>
          <img alt="" height={20} src={asset.icon} width={20} />
          <span {...styles.text()}>{asset.name}</span>
          <span {...styles.suffix()}>{asset.balance}</span>
          <span {...styles.check()}>{asset.selected && <Check />}</span>
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const check = style({ display: 'flex', width: '16px !custom' })

  export const item = style({
    alignItems: 'center',
    borderRadius: 'xs',
    color: 'content.primary',
    display: 'flex',
    gap: '8',
    minHeight: '40',
    paddingInline: '12',
    typography: 'body.b2',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    padding: '8',
    width: '16rem !custom',
  })

  export const suffix = style({ color: 'content.secondary', typography: 'body.b3' })

  export const text = style({ flex: '1 !custom' })
}
```

**Don't:** Pack names, details, and balances into the option text.

```tsx
/**
 * Don't example for "Keep Option Rows Scannable" on the Select page.
 * Don't pack names, details, and balances into the option text.
 * @module
 */
import { Check } from '@tempoxyz/ds/icons'
import { style } from '@tempoxyz/ds'

const assets = [
  { label: 'pathUSD, Tempo stablecoin, balance 1,250.00', selected: true },
  { label: 'USDC.e, bridged USD Coin, balance 480.25', selected: false },
  { label: 'USDT0, bridged Tether, balance 12.00', selected: false },
]

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      {assets.map((asset) => (
        <div key={asset.label} {...styles.item()}>
          <span {...styles.text()}>{asset.label}</span>
          <span {...styles.check()}>{asset.selected && <Check />}</span>
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const check = style({ display: 'flex', flexShrink: '0 !custom', width: '16px !custom' })

  export const item = style({
    alignItems: 'center',
    borderRadius: 'xs',
    color: 'content.primary',
    display: 'flex',
    gap: '8',
    minHeight: '40',
    paddingInline: '12',
    typography: 'body.b2',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    padding: '8',
    width: '16rem !custom',
  })

  export const text = style({
    flex: '1 !custom',
    minWidth: '0 !custom',
    overflow: 'hidden',
    textOverflow: 'ellipsis',
    whiteSpace: 'nowrap',
  })
}
```

## Accessibility

Select handles arrow keys, typeahead, and Escape. It follows the [WAI-ARIA Authoring Practices select-only combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/).

### Semantics

* **Select.Trigger (combobox):** A button that announces its popup and whether the list is open.
* **Select.Popup and Select.Item (listbox):** The list renders in a portal. The selected option shows a check, not only a color.
* **Select.Group (group):** A set of related options, named by the group label inside it.
* **Invalid and Disabled (aria-invalid):** `invalid` marks the trigger and fills it red. `disabled` removes it from the tab order.
* **Select.Icon (aria-hidden):** Decorative, so it is hidden from assistive technology and not announced.
* **Target Size (48px):** The trigger matches the 48px field, above the 24px WCAG 2.2 minimum.

### Keyboard

* **Move to the Trigger (Tab):** Moves focus to the trigger.
* **Open the List (Enter, Space, or Down Arrow):** Opens the list and focuses the selected option.
* **Move Between Options (Down Arrow and Up Arrow):** Move focus to the next or previous option.
* **Jump to the Ends (Home and End):** Move focus to the first or last option.
* **Type to Find (Character):** Focuses the next option starting with that key.
* **Select an Option (Enter or Space):** On an option, selects it and closes the list.
* **Close the List (Escape):** Keeps the value and returns focus to the trigger.

### Your Responsibilities

* **Name the Trigger (Field.Label):** Use a visible field label. If none fits, set `aria-label`.
* **Explain Invalid Values (Field.Error):** Explain invalid values in text, not only the red fill.

## Related

[Combobox](/docs/components/combobox)

Use for long, filterable lists.

[RadioGroup](/docs/components/radio-group)

Use for a few options shown at once.

[ChoiceGroup](/docs/components/choice-group)

Use for switching views.

[Menu](/docs/components/menu)

Use for lists of actions.

[Dashboards](/docs/patterns/dashboards)

Covers filter bars and controls.
