# Combobox

A text input that filters a list of fixed options while people type.

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

## Overview

A text input with a listbox popup. The value must be one of the options.

## Examples

### Basic

```tsx
import { Combobox } from '@tempoxyz/ds'
import { Search } from '@tempoxyz/ds/icons'
import { useState } from 'react'
import cbBtc from '../../coins/CbBTC.svg'
import ethereumEth from '../../coins/EthereumETH.svg'
import pathUsd from '../../coins/PathUSD.svg'
import usdce from '../../coins/USDCe.svg'
import usdt0 from '../../coins/USDT0.svg'

const coins: Record<string, string> = {
  'Bridged ETH': ethereumEth,
  pathUSD: pathUsd,
  Tether: usdt0,
  'USDC.e': usdce,
  USDT0: usdt0,
  'Wrapped BTC': cbBtc,
}

const assets = ['pathUSD', 'USDC.e', 'Tether', 'USDT0', 'Bridged ETH', 'Wrapped BTC']

function Coin(props: { asset: string }) {
  return <img alt="" height={20} src={coins[props.asset]} width={20} />
}

function Single(props: Pick<Combobox.InputGroup.Props, 'invalid' | 'variant'>) {
  const [value, setValue] = useState<string | null>('pathUSD')

  return (
    <Combobox.Root items={assets} onValueChange={setValue} value={value}>
      <Combobox.InputGroup {...props}>
        <Combobox.Prefix>{value ? <Coin asset={value} /> : <Search />}</Combobox.Prefix>
        <Combobox.Input aria-label="Asset" placeholder="Search assets" />
        <Combobox.Clear />
        <Combobox.Trigger />
      </Combobox.InputGroup>
      <Combobox.Popup>
        <Combobox.Empty>No results</Combobox.Empty>
        <Combobox.List>
          {(asset: string) => (
            <Combobox.Item key={asset} value={asset}>
              <Combobox.ItemPrefix>
                <Coin asset={asset} />
              </Combobox.ItemPrefix>
              <Combobox.ItemText>{asset}</Combobox.ItemText>
            </Combobox.Item>
          )}
        </Combobox.List>
      </Combobox.Popup>
    </Combobox.Root>
  )
}

export function Demo() {
  return <Single />
}
```

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

### Variant

Set `variant` on `Combobox.InputGroup` to `filled` (default) or `outlined`.

```tsx
import { Combobox, style } from '@tempoxyz/ds'
import { Search } from '@tempoxyz/ds/icons'
import { useState } from 'react'
import cbBtc from '../../coins/CbBTC.svg'
import ethereumEth from '../../coins/EthereumETH.svg'
import pathUsd from '../../coins/PathUSD.svg'
import usdce from '../../coins/USDCe.svg'
import usdt0 from '../../coins/USDT0.svg'

const coins: Record<string, string> = {
  'Bridged ETH': ethereumEth,
  pathUSD: pathUsd,
  Tether: usdt0,
  'USDC.e': usdce,
  USDT0: usdt0,
  'Wrapped BTC': cbBtc,
}

const assets = ['pathUSD', 'USDC.e', 'Tether', 'USDT0', 'Bridged ETH', 'Wrapped BTC']

function Coin(props: { asset: string }) {
  return <img alt="" height={20} src={coins[props.asset]} width={20} />
}

function Single(props: Pick<Combobox.InputGroup.Props, 'invalid' | 'variant'>) {
  const [value, setValue] = useState<string | null>('pathUSD')

  return (
    <Combobox.Root items={assets} onValueChange={setValue} value={value}>
      <Combobox.InputGroup {...props}>
        <Combobox.Prefix>{value ? <Coin asset={value} /> : <Search />}</Combobox.Prefix>
        <Combobox.Input aria-label="Asset" placeholder="Search assets" />
        <Combobox.Clear />
        <Combobox.Trigger />
      </Combobox.InputGroup>
      <Combobox.Popup>
        <Combobox.Empty>No results</Combobox.Empty>
        <Combobox.List>
          {(asset: string) => (
            <Combobox.Item key={asset} value={asset}>
              <Combobox.ItemPrefix>
                <Coin asset={asset} />
              </Combobox.ItemPrefix>
              <Combobox.ItemText>{asset}</Combobox.ItemText>
            </Combobox.Item>
          )}
        </Combobox.List>
      </Combobox.Popup>
    </Combobox.Root>
  )
}

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Single />
      <Single variant="outlined" />
    </div>
  )
}

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

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

### Invalid

Set `invalid` on `Combobox.InputGroup` to style the frame, and `aria-invalid` on the input to expose the state.

```tsx
import { Combobox } from '@tempoxyz/ds'
import { Search } from '@tempoxyz/ds/icons'
import { useState } from 'react'
import cbBtc from '../../coins/CbBTC.svg'
import ethereumEth from '../../coins/EthereumETH.svg'
import pathUsd from '../../coins/PathUSD.svg'
import usdce from '../../coins/USDCe.svg'
import usdt0 from '../../coins/USDT0.svg'

const coins: Record<string, string> = {
  'Bridged ETH': ethereumEth,
  pathUSD: pathUsd,
  Tether: usdt0,
  'USDC.e': usdce,
  USDT0: usdt0,
  'Wrapped BTC': cbBtc,
}

const assets = ['pathUSD', 'USDC.e', 'Tether', 'USDT0', 'Bridged ETH', 'Wrapped BTC']

function Coin(props: { asset: string }) {
  return <img alt="" height={20} src={coins[props.asset]} width={20} />
}

function Single(props: Pick<Combobox.InputGroup.Props, 'invalid' | 'variant'>) {
  const [value, setValue] = useState<string | null>('pathUSD')

  return (
    <Combobox.Root items={assets} onValueChange={setValue} value={value}>
      <Combobox.InputGroup {...props}>
        <Combobox.Prefix>{value ? <Coin asset={value} /> : <Search />}</Combobox.Prefix>
        <Combobox.Input aria-label="Asset" placeholder="Search assets" />
        <Combobox.Clear />
        <Combobox.Trigger />
      </Combobox.InputGroup>
      <Combobox.Popup>
        <Combobox.Empty>No results</Combobox.Empty>
        <Combobox.List>
          {(asset: string) => (
            <Combobox.Item key={asset} value={asset}>
              <Combobox.ItemPrefix>
                <Coin asset={asset} />
              </Combobox.ItemPrefix>
              <Combobox.ItemText>{asset}</Combobox.ItemText>
            </Combobox.Item>
          )}
        </Combobox.List>
      </Combobox.Popup>
    </Combobox.Root>
  )
}

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

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

### Multiple

Set `multiple` on `Combobox.Root` to select several values, shown as chips.

```tsx
import { Combobox } from '@tempoxyz/ds'
import { useState } from 'react'

const assets = ['pathUSD', 'USDC.e', 'Tether', 'USDT0', 'Bridged ETH', 'Wrapped BTC']

function Multiple() {
  const [value, setValue] = useState(['pathUSD', 'USDC.e'])

  return (
    <Combobox.Root items={assets} multiple onValueChange={setValue} value={value}>
      <Combobox.InputGroup>
        <Combobox.Value>
          {(selected: string[]) => (
            <Combobox.Chips aria-label="Selected assets">
              {selected.map((asset) => (
                <Combobox.Chip key={asset}>
                  {asset}
                  <Combobox.ChipRemove aria-label={`Remove ${asset}`} />
                </Combobox.Chip>
              ))}
              <Combobox.Input
                aria-label="Assets"
                placeholder={selected.length ? '' : 'Add assets'}
              />
            </Combobox.Chips>
          )}
        </Combobox.Value>
      </Combobox.InputGroup>
      <Combobox.Popup>
        <Combobox.Empty>No results</Combobox.Empty>
        <Combobox.List>
          {(asset: string) => (
            <Combobox.Item key={asset} value={asset}>
              <Combobox.ItemText>{asset}</Combobox.ItemText>
            </Combobox.Item>
          )}
        </Combobox.List>
      </Combobox.Popup>
    </Combobox.Root>
  )
}

export function Demo() {
  return <Multiple />
}
```

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

## Anatomy

Import the component and assemble its parts.

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

<Combobox.Root>
  <Combobox.InputGroup>
    <Combobox.Prefix />
    <Combobox.Value>
      <Combobox.Chips>
        <Combobox.Chip>
          <Combobox.ChipRemove />
        </Combobox.Chip>
        <Combobox.Input />
      </Combobox.Chips>
    </Combobox.Value>
    <Combobox.Clear />
    <Combobox.Trigger />
  </Combobox.InputGroup>
  <Combobox.Popup>
    <Combobox.Empty />
    <Combobox.List>
      <Combobox.Group>
        <Combobox.GroupLabel />
        <Combobox.Collection>
          <Combobox.Item>
            <Combobox.ItemPrefix />
            <Combobox.ItemText />
            <Combobox.ItemSuffix />
          </Combobox.Item>
        </Combobox.Collection>
      </Combobox.Group>
      <Combobox.Separator />
    </Combobox.List>
  </Combobox.Popup>
</Combobox.Root>
```

## Guidelines

### When to Use

* Choose one item from a long, fixed list filtered by typing, such as the asset to send or the country on an account.
* Choose several items from that list with `multiple`, such as the assets a report covers.

### When Not to Use

* If people can scan the whole list without typing, use [Select](/docs/components/select).
* If any typed text is a valid value, such as a recipient address, use [Autocomplete](/docs/components/autocomplete).
* Use [RadioGroup](/docs/components/radio-group) or [ChoiceGroup](/docs/components/choice-group) for a few options that fit on screen.
* Use [CheckboxGroup](/docs/components/checkbox-group) for several options from a short list.

### Keep a Visible Label

The placeholder disappears on input, so it can't name the field.

**Do:** Label the field and show the selected asset's icon in `Combobox.Prefix`.

```tsx
/**
 * Do example for "Keep a Visible Label" on the Combobox page.
 * Label the field and show the selected asset's icon in `Combobox.Prefix`.
 * @module
 */
import { Combobox, Field, style } from '@tempoxyz/ds'
import usdce from '../../coins/USDCe.svg'

const assets = ['pathUSD', 'USDC.e', 'USDT0']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Asset</Field.Label>
      <Combobox.Root defaultValue="USDC.e" items={assets}>
        <Combobox.InputGroup>
          <Combobox.Prefix>
            <img alt="" height={20} src={usdce} width={20} />
          </Combobox.Prefix>
          <Combobox.Input placeholder="Search assets" />
          <Combobox.Trigger />
        </Combobox.InputGroup>
        <Combobox.Popup>
          <Combobox.Empty>No assets found</Combobox.Empty>
          <Combobox.List>
            {(asset: string) => (
              <Combobox.Item key={asset} value={asset}>
                <Combobox.ItemText>{asset}</Combobox.ItemText>
              </Combobox.Item>
            )}
          </Combobox.List>
        </Combobox.Popup>
      </Combobox.Root>
    </Field.Root>
  )
}

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

**Don't:** Rely on the placeholder to say what the field is for.

```tsx
/**
 * Don't example for "Keep a Visible Label" on the Combobox page.
 * Don't rely on the placeholder to say what the field is for.
 * @module
 */
import { Combobox, style } from '@tempoxyz/ds'
import { Search } from '@tempoxyz/ds/icons'

const assets = ['pathUSD', 'USDC.e', 'USDT0']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Combobox.Root items={assets}>
      <Combobox.InputGroup {...styles.group()}>
        <Combobox.Prefix>
          <Search />
        </Combobox.Prefix>
        <Combobox.Input aria-label="Asset" placeholder="Search assets" />
        <Combobox.Trigger />
      </Combobox.InputGroup>
      <Combobox.Popup>
        <Combobox.Empty>No assets found</Combobox.Empty>
        <Combobox.List>
          {(asset: string) => (
            <Combobox.Item key={asset} value={asset}>
              <Combobox.ItemText>{asset}</Combobox.ItemText>
            </Combobox.Item>
          )}
        </Combobox.List>
      </Combobox.Popup>
    </Combobox.Root>
  )
}

namespace styles {
  export const group = style({ width: '100% !custom' })
}
```

### Always Render Combobox.Empty

`Combobox.Empty` shows its children when nothing matches and announces them in a polite status region.

**Do:** Render a short, specific message, such as No assets found.

```tsx
/**
 * Do example for "Always Render Combobox.Empty" on the Combobox page.
 * Render a short, specific message, such as No assets found.
 * @module
 */
import { Combobox, style } from '@tempoxyz/ds'

const assets = ['pathUSD', 'USDC.e', 'USDT0']

// The popup portals and opens on input, so a static copy shows it open.
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.column()}>
      <Combobox.Root defaultInputValue="EURC" items={assets}>
        <Combobox.InputGroup>
          <Combobox.Input aria-label="Asset" />
          <Combobox.Trigger />
        </Combobox.InputGroup>
      </Combobox.Root>
      <div {...styles.popup()}>
        <div {...styles.empty()}>No assets found</div>
      </div>
    </div>
  )
}

namespace styles {
  export const column = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '8',
    maxWidth: '16rem !custom',
    width: '100% !custom',
  })

  export const empty = style({
    color: 'content.secondary',
    paddingBlock: '12',
    paddingInline: '16',
    typography: 'body.b2',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    padding: '6px !custom',
  })
}
```

**Don't:** Leave it out. The popup opens blank and announces nothing.

```tsx
/**
 * Don't example for "Always Render Combobox.Empty" on the Combobox page.
 * Don't leave it out. The popup opens blank and announces nothing.
 * @module
 */
import { Combobox, style } from '@tempoxyz/ds'

const assets = ['pathUSD', 'USDC.e', 'USDT0']

// The popup portals and opens on input, so a static copy shows it open.
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.column()}>
      <Combobox.Root defaultInputValue="EURC" items={assets}>
        <Combobox.InputGroup>
          <Combobox.Input aria-label="Asset" />
          <Combobox.Trigger />
        </Combobox.InputGroup>
      </Combobox.Root>
      <div {...styles.popup()} />
    </div>
  )
}

namespace styles {
  export const column = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '8',
    maxWidth: '16rem !custom',
    width: '100% !custom',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    padding: '6px !custom',
  })
}
```

### Show What Identifies Each Item

* **`Combobox.ItemText`:** The searchable name, such as the symbol USDC.e.
* **`Combobox.ItemPrefix`:** A token icon.
* **`Combobox.ItemSuffix`:** Detail that informs the choice, such as a balance.

**Do:** Show the symbol, its icon, and the balance.

```tsx
/**
 * Do example for "Show What Identifies Each Item" on the Combobox page.
 * Show the symbol, its icon, and the balance.
 * @module
 */
import pathusd from '../../coins/PathUSD.svg'
import usdce from '../../coins/USDCe.svg'
import usdt0 from '../../coins/USDT0.svg'
import { style } from '@tempoxyz/ds'

const assets = [
  { balance: '1,250.00', icon: usdce, symbol: 'USDC.e' },
  { balance: '80.50', icon: pathusd, symbol: 'pathUSD' },
  { balance: '0.00', icon: usdt0, symbol: 'USDT0' },
]

// A static copy of the open popup, since the real one portals and opens on input.
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      {assets.map((asset) => (
        <div key={asset.symbol} {...styles.item()}>
          <img alt="" height={20} src={asset.icon} width={20} />
          {asset.symbol}
          <span {...styles.suffix()}>{asset.balance}</span>
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const item = style({
    alignItems: 'center',
    display: 'flex',
    gap: '8',
    minHeight: '40',
    paddingInline: '16',
    typography: 'body.b2Strong',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    padding: '6px !custom',
    width: '16rem !custom',
  })

  export const suffix = style({
    color: 'content.secondary',
    marginInlineStart: 'auto !custom',
    typography: 'body.b3',
  })
}
```

**Don't:** List contract addresses as item text.

```tsx
/**
 * Don't example for "Show What Identifies Each Item" on the Combobox page.
 * Don't list contract addresses as item text.
 * @module
 */
import { style } from '@tempoxyz/ds'

const assets = ['0x20c0…0001', '0x20c0…0002', '0x20c0…0003']

// A static copy of the open popup, since the real one portals and opens on input.
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      {assets.map((address) => (
        <div key={address} {...styles.item()}>
          {address}
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const item = style({
    alignItems: 'center',
    display: 'flex',
    gap: '8',
    minHeight: '40',
    paddingInline: '16',
    typography: 'body.b2Strong',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    padding: '6px !custom',
    width: '16rem !custom',
  })
}
```

### Offer a Way to Browse

`Combobox.Clear` mounts only while there is a value.

**Do:** Add `Combobox.Trigger` to open the full list, and `Combobox.Clear` if the value can be emptied.

```tsx
/**
 * Do example for "Offer a Way to Browse" on the Combobox page.
 * Add `Combobox.Trigger` to open the full list, and `Combobox.Clear` if the value can be emptied.
 * @module
 */
import { Combobox, Field, style } from '@tempoxyz/ds'

const countries = ['Germany', 'Singapore', 'United States']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Country</Field.Label>
      <Combobox.Root defaultValue="Singapore" items={countries}>
        <Combobox.InputGroup>
          <Combobox.Input placeholder="Search countries" />
          <Combobox.Clear />
          <Combobox.Trigger />
        </Combobox.InputGroup>
      </Combobox.Root>
    </Field.Root>
  )
}

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

**Don't:** Make typing the only way to see the options.

```tsx
/**
 * Don't example for "Offer a Way to Browse" on the Combobox page.
 * Don't make typing the only way to see the options.
 * @module
 */
import { Combobox, Field, style } from '@tempoxyz/ds'

const countries = ['Germany', 'Singapore', 'United States']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Country</Field.Label>
      <Combobox.Root defaultValue="Singapore" items={countries}>
        <Combobox.InputGroup>
          <Combobox.Input placeholder="Search countries" />
        </Combobox.InputGroup>
      </Combobox.Root>
    </Field.Root>
  )
}

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

### Group Long Lists

Name each `Combobox.Group` with a `Combobox.GroupLabel`, and divide groups with `Combobox.Separator`. Put the most-chosen items first.

**Do:** Split a long list into named sections, such as Stablecoins.

```tsx
/**
 * Do example for "Group Long Lists" on the Combobox page.
 * Split a long list into named sections, such as Stablecoins.
 * @module
 */
import { style } from '@tempoxyz/ds'

// A static copy of the open popup, since the real one portals and opens on input.
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <div {...styles.label()}>Stablecoins</div>
      <div {...styles.item()}>pathUSD</div>
      <div {...styles.item()}>USDC.e</div>
      <div {...styles.separator()} />
      <div {...styles.label()}>Other assets</div>
      <div {...styles.item()}>cbBTC</div>
      <div {...styles.item()}>ETH</div>
    </div>
  )
}

namespace styles {
  export const item = style({
    alignItems: 'center',
    display: 'flex',
    minHeight: '40',
    paddingInline: '16',
    typography: 'body.b2Strong',
  })

  export const label = style({
    color: 'content.secondary',
    paddingBlock: '8',
    paddingInline: '16',
    typography: 'body.b3',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    padding: '6px !custom',
    width: '16rem !custom',
  })

  export const separator = style({
    backgroundColor: 'container.strong',
    height: '1',
    marginBlock: '8',
    marginInline: '16',
  })
}
```

**Don't:** Mix unrelated kinds of items in one flat list.

```tsx
/**
 * Don't example for "Group Long Lists" on the Combobox page.
 * Don't mix unrelated kinds of items in one flat list.
 * @module
 */
import { style } from '@tempoxyz/ds'

// A static copy of the open popup, since the real one portals and opens on input.
/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <div {...styles.item()}>cbBTC</div>
      <div {...styles.item()}>pathUSD</div>
      <div {...styles.item()}>ETH</div>
      <div {...styles.item()}>USDC.e</div>
    </div>
  )
}

namespace styles {
  export const item = style({
    alignItems: 'center',
    display: 'flex',
    minHeight: '40',
    paddingInline: '16',
    typography: 'body.b2Strong',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    padding: '6px !custom',
    width: '16rem !custom',
  })
}
```

### Expose Errors on the Input

**Do:** Set `aria-invalid` on `Combobox.Input`, and explain the problem in a `Field.Error`.

```tsx
/**
 * Do example for "Expose Errors on the TextInput" on the Combobox page.
 * Set `aria-invalid` on `Combobox.Input`, and explain the problem in a `Field.Error`.
 * @module
 */
import { Combobox, Field, style } from '@tempoxyz/ds'

const assets = ['pathUSD', 'USDC.e', 'USDT0']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root invalid {...styles.field()}>
      <Field.Label>Asset</Field.Label>
      <Combobox.Root items={assets}>
        <Combobox.InputGroup invalid>
          <Combobox.Input aria-invalid placeholder="Search assets" />
          <Combobox.Trigger />
        </Combobox.InputGroup>
      </Combobox.Root>
      <Field.Error match>Select an asset to send</Field.Error>
    </Field.Root>
  )
}

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

**Don't:** Rely on `invalid` on `Combobox.InputGroup`. It only styles the frame.

```tsx
/**
 * Don't example for "Expose Errors on the TextInput" on the Combobox page.
 * Don't rely on `invalid` on `Combobox.InputGroup`. It only styles the frame.
 * @module
 */
import { Combobox, Field, style } from '@tempoxyz/ds'

const assets = ['pathUSD', 'USDC.e', 'USDT0']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Asset</Field.Label>
      <Combobox.Root items={assets}>
        <Combobox.InputGroup invalid>
          <Combobox.Input placeholder="Search assets" />
          <Combobox.Trigger />
        </Combobox.InputGroup>
      </Combobox.Root>
    </Field.Root>
  )
}

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

## Content

* **Label:** The noun the value names, such as Asset, Network, or Country.
* **Placeholder:** What people can search by, such as Search by name or symbol.
* **Items:** The names and symbols from the token list, with the same casing everywhere.

## Accessibility

Follows the [WAI-ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) with list autocomplete.

### Semantics

* **Combobox.Input (combobox):** A text input that announces an option list and whether it is open.
* **Highlighted Option (aria-activedescendant):** Points to the highlighted option while focus stays in the input.
* **Combobox.List and Combobox.Item (listbox):** Each item is an option with a check mark while selected.
* **Combobox.Trigger and Combobox.Clear (button):** Named "Show options" and "Clear", both out of the tab order. Clear renders only with a value.
* **Combobox.Chips (toolbar):** With `multiple`, arrow keys move between chips. Each remove button is named "Remove".

### Keyboard

* **Move Focus to the TextInput (Tab):** Moves focus to the input.
* **Filter the Options (Typing):** Filters the options and opens the list.
* **Open or Move Down (Down Arrow):** Opens the list, or highlights the next option.
* **Move Up (Up Arrow):** Highlights the previous option.
* **Select an Option (Enter):** Selects the highlighted option and closes the list. With `multiple`, toggles it instead.
* **Close the List (Escape):** Closes the popup.
* **Move to the Chips (Left Arrow):** With `multiple`, from the start of the input, focuses the last chip. Arrows move between chips.
* **Remove a Chip (Backspace):** With `multiple`, removes the focused chip, or the last chip from an empty input.

### Focus

DOM focus stays on the input while the arrow keys move the highlight. Chips take focus only through the arrow keys, not Tab.

### Announcements

* **Highlighted Option (aria-activedescendant):** Screen readers announce each option on highlight.
* **Empty Results (status):** Announces a query without matches.

### Your Responsibilities

* **Name Chips in Multiple Mode (aria-label):** Name the chips, such as "Selected assets", and each remove button by its value, such as "Remove USDC".
* **Hide Item Icons (alt):** Leave item icon alt text empty. The item text names the item.

## Related

[Autocomplete](/docs/components/autocomplete)

Use for free text with suggestions.

[Select](/docs/components/select)

Use for short lists.

[Field](/docs/components/field)

Use for the label and error.

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

Use for token icons in items.

[Blockchain Values](/docs/patterns/blockchain-values)

Covers showing assets and addresses.
