# ChoiceGroup

A segmented control for a few mutually exclusive options.

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

Figma: [Base - Segment Item](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3075-548) (`ChoiceGroup.Item`), [Controls/Segmented Control Item Small](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5484) (`ChoiceGroup.Item`), [Segmented Control](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3075-535) (`ChoiceGroup.Root`)

## Overview

A single-select control with radio semantics. One option is always selected.

## Examples

### Basic

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

export function Demo() {
  return (
    <ChoiceGroup.Root aria-label="Amount" defaultValue="50">
      <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
      <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
      <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
    </ChoiceGroup.Root>
  )
}
```

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

### Size

Set `size` to `small`, `medium` (default), or `large`.

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

export function Demo() {
  return (
    <div {...styles.stack()}>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <ChoiceGroup.Root aria-label={`Amount ${size}`} defaultValue="50" key={size} size={size}>
          <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
          <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
          <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
        </ChoiceGroup.Root>
      ))}
    </div>
  )
}

namespace styles {
  export const stack = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    gap: '16',
  })
}
```

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

### Variant

Set `variant` to `default` or `chips`. `chips` renders a horizontally scrolling row of chips, with an optional `ChoiceGroup.ItemIcon`.

```tsx
import { ChoiceGroup, style } from '@tempoxyz/ds'
import { Coins, Ethereum, Globe } from '@tempoxyz/ds/icons'

const networks = [
  { icon: <Coins />, label: 'Tempo' },
  { icon: <Ethereum />, label: 'Ethereum' },
  { icon: <Globe />, label: 'Base' },
  { icon: <Globe />, label: 'Arbitrum' },
  { icon: <Globe />, label: 'Optimism' },
]

export function Demo() {
  return (
    <div {...styles.stack()}>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <ChoiceGroup.Root
          aria-label={`Network ${size}`}
          defaultValue="Tempo"
          key={size}
          size={size}
          variant="chips"
        >
          {networks.map((network) => (
            <ChoiceGroup.Item key={network.label} value={network.label}>
              <ChoiceGroup.ItemIcon>{network.icon}</ChoiceGroup.ItemIcon>
              {network.label}
            </ChoiceGroup.Item>
          ))}
        </ChoiceGroup.Root>
      ))}
    </div>
  )
}

namespace styles {
  export const stack = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    gap: '16',
  })
}
```

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

### Field

Wrap the group in a `Field.Root`. The `Field.Label` names the group, and a `Field.Description` adds a hint below it.

```tsx
import { ChoiceGroup, Field, style } from '@tempoxyz/ds'
import { Coins, Ethereum, Globe } from '@tempoxyz/ds/icons'

const networks = [
  { icon: <Coins />, label: 'Tempo' },
  { icon: <Ethereum />, label: 'Ethereum' },
  { icon: <Globe />, label: 'Base' },
]

export function Demo() {
  return (
    <div {...styles.stack()}>
      <Field.Root>
        <Field.Label>Amount</Field.Label>
        <ChoiceGroup.Root defaultValue="50">
          <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
          <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
          <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
        </ChoiceGroup.Root>
        <Field.Description>Charged to your saved card.</Field.Description>
      </Field.Root>
      <Field.Root>
        <Field.Label>Network</Field.Label>
        <ChoiceGroup.Root defaultValue="Tempo" variant="chips">
          {networks.map((network) => (
            <ChoiceGroup.Item key={network.label} value={network.label}>
              <ChoiceGroup.ItemIcon>{network.icon}</ChoiceGroup.ItemIcon>
              {network.label}
            </ChoiceGroup.Item>
          ))}
        </ChoiceGroup.Root>
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const stack = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '24',
    maxWidth: '320px !custom',
  })
}
```

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

### Disabled

Set `disabled` on a `ChoiceGroup.Item` to make one option unavailable.

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

export function Demo() {
  return (
    <ChoiceGroup.Root aria-label="Amount" defaultValue="50">
      <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
      <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
      <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
      <ChoiceGroup.Item disabled value="other">
        Other
      </ChoiceGroup.Item>
    </ChoiceGroup.Root>
  )
}
```

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

## Anatomy

Import the component and assemble its parts.

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

<ChoiceGroup.Root>
  <ChoiceGroup.Item>
    <ChoiceGroup.ItemIcon />
  </ChoiceGroup.Item>
</ChoiceGroup.Root>
```

## Guidelines

### When to Use

* Switch between two to four short options that change a view, such as the 1H, 24H, 7D, and 30D range on a TPS chart.
* Pick a preset value, such as $20, $50, or $100 on Add funds.
* Filter by one option from a longer set with `variant="chips"`, such as the network for a deposit.

### When Not to Use

* If options need longer labels or are submitted with a form, use [RadioGroup](/docs/components/radio-group).
* Use [Select](/docs/components/select) for many options, or when space is limited.
* Use [Tabs](/docs/components/tabs) to switch between panels, such as Overview, Activity, and Settings.
* If each option needs an icon and a description, use [Choicebox](/docs/components/choicebox).
* Use [Switch](/docs/components/switch) for an on or off setting, not On and Off segments.
* Use [Button](/docs/components/button) for actions such as Send, Receive, and Swap.

### Keep Options Few and Short

Use two to four options of one or two words each, at similar lengths. Items never wrap.

**Do:** Use short, parallel labels that fit side by side.

```tsx
/**
 * Do example for "Keep Options Few and Short" on the ChoiceGroup page.
 * Use short, parallel labels that fit side by side.
 * @module
 */
import { ChoiceGroup } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ChoiceGroup.Root aria-label="Time range" defaultValue="24h">
      <ChoiceGroup.Item value="1h">1H</ChoiceGroup.Item>
      <ChoiceGroup.Item value="24h">24H</ChoiceGroup.Item>
      <ChoiceGroup.Item value="7d">7D</ChoiceGroup.Item>
      <ChoiceGroup.Item value="30d">30D</ChoiceGroup.Item>
    </ChoiceGroup.Root>
  )
}
```

**Don't:** Use phrases that overflow the control.

```tsx
/**
 * Don't example for "Keep Options Few and Short" on the ChoiceGroup page.
 * Don't use phrases that overflow the control.
 * @module
 */
import { ChoiceGroup } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ChoiceGroup.Root aria-label="Time range" defaultValue="24h">
      <ChoiceGroup.Item value="1h">Last hour</ChoiceGroup.Item>
      <ChoiceGroup.Item value="24h">Last 24 hours</ChoiceGroup.Item>
      <ChoiceGroup.Item value="7d">Last 7 days</ChoiceGroup.Item>
      <ChoiceGroup.Item value="30d">Last 30 days</ChoiceGroup.Item>
    </ChoiceGroup.Root>
  )
}
```

### Always Keep One Option Selected

The selection can't be cleared.

**Do:** On first render, set `defaultValue`, or `value` with `onValueChange`, to the current mode.

```tsx
/**
 * Do example for "Always Keep One Option Selected" on the ChoiceGroup page.
 * On first render, set `defaultValue`, or `value` with `onValueChange`, to the current mode.
 * @module
 */
import { ChoiceGroup } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ChoiceGroup.Root aria-label="Amount" defaultValue="50">
      <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
      <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
      <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
    </ChoiceGroup.Root>
  )
}
```

**Don't:** Render the group with no option selected.

```tsx
/**
 * Don't example for "Always Keep One Option Selected" on the ChoiceGroup page.
 * Don't render the group with no option selected.
 * @module
 */
import { ChoiceGroup } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ChoiceGroup.Root aria-label="Amount">
      <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
      <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
      <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
    </ChoiceGroup.Root>
  )
}
```

### Apply the Choice Immediately

If the choice waits for a form submit, use [RadioGroup](/docs/components/radio-group).

**Do:** Update the view when the selection changes, such as redrawing the chart for 7D.

```tsx
/**
 * Do example for "Apply the Choice Immediately" on the ChoiceGroup page.
 * Update the view when the selection changes, such as redrawing the chart for 7D.
 * @module
 */
import { ChoiceGroup } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ChoiceGroup.Root aria-label="Time range" defaultValue="24h" size="small">
      <ChoiceGroup.Item value="1h">1H</ChoiceGroup.Item>
      <ChoiceGroup.Item value="24h">24H</ChoiceGroup.Item>
      <ChoiceGroup.Item value="7d">7D</ChoiceGroup.Item>
      <ChoiceGroup.Item value="30d">30D</ChoiceGroup.Item>
    </ChoiceGroup.Root>
  )
}
```

**Don't:** Add an Apply button.

```tsx
/** Don't example for "Apply the Choice Immediately" on the ChoiceGroup page. Don't add an Apply button. @module */
import { Button, ChoiceGroup, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <ChoiceGroup.Root aria-label="Time range" defaultValue="24h" size="small">
        <ChoiceGroup.Item value="1h">1H</ChoiceGroup.Item>
        <ChoiceGroup.Item value="24h">24H</ChoiceGroup.Item>
        <ChoiceGroup.Item value="7d">7D</ChoiceGroup.Item>
        <ChoiceGroup.Item value="30d">30D</ChoiceGroup.Item>
      </ChoiceGroup.Root>
      <Button size="small" variant="secondary">
        Apply
      </Button>
    </div>
  )
}

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

### Choose a Variant by Option Count

* **Few Short Options (default):** Two to four options in one track, marked by a sliding pill.
* **Longer Filter Sets (chips):** A scrolling row of chips for options that outgrow the width, such as networks for a deposit.

### Match the Height of Nearby Controls

`small`, `medium`, and `large` tracks are 32, 48, and 56px tall. A `medium` track fills its row and gives each item an equal width, as tall as [TextInput](/docs/components/text-input).

**Do:** Use `small` in a dashboard toolbar beside a small [Select](/docs/components/select).

```tsx
/**
 * Do example for "Match the Height of Nearby Controls" on the ChoiceGroup page.
 * Use `small` in a dashboard toolbar beside a small Select.
 * @module
 */
import { ChoiceGroup, Select, style } from '@tempoxyz/ds'

const items = { usdc: 'USDC', usdt: 'USDT' }

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.toolbar()}>
      <ChoiceGroup.Root aria-label="Time range" defaultValue="24h" size="small">
        <ChoiceGroup.Item value="1h">1H</ChoiceGroup.Item>
        <ChoiceGroup.Item value="24h">24H</ChoiceGroup.Item>
        <ChoiceGroup.Item value="7d">7D</ChoiceGroup.Item>
      </ChoiceGroup.Root>
      <Select.Root aria-label="Asset" defaultValue="usdc" items={items}>
        <Select.Trigger {...styles.select()}>
          <Select.Value />
          <Select.Icon />
        </Select.Trigger>
      </Select.Root>
    </div>
  )
}

namespace styles {
  export const toolbar = style({ alignItems: 'center', display: 'flex', gap: '8' })

  export const select = style({ width: '7rem !custom' })
}
```

**Don't:** Mix sizes in one toolbar.

```tsx
/**
 * Don't example for "Match the Height of Nearby Controls" on the ChoiceGroup page.
 * Don't mix sizes in one toolbar.
 * @module
 */
import { ChoiceGroup, Select, style } from '@tempoxyz/ds'

const items = { usdc: 'USDC', usdt: 'USDT' }

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.toolbar()}>
      <ChoiceGroup.Root aria-label="Time range" defaultValue="24h" size="large">
        <ChoiceGroup.Item value="1h">1H</ChoiceGroup.Item>
        <ChoiceGroup.Item value="24h">24H</ChoiceGroup.Item>
        <ChoiceGroup.Item value="7d">7D</ChoiceGroup.Item>
      </ChoiceGroup.Root>
      <Select.Root aria-label="Asset" defaultValue="usdc" items={items}>
        <Select.Trigger {...styles.select()}>
          <Select.Value />
          <Select.Icon />
        </Select.Trigger>
      </Select.Root>
    </div>
  )
}

namespace styles {
  export const toolbar = style({ alignItems: 'center', display: 'flex', gap: '8' })

  export const select = style({ width: '7rem !custom' })
}
```

## Content

* Write labels as compact units, such as 1H and 7D, or as words. Use one style across all options, and don't mix 1 hour with 7D, or Ethereum with ETH.
* Use numerals for numbers and amounts, such as $20 and 30D.

## Accessibility

Follows the [WAI-ARIA radio group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).

### Semantics

* **ChoiceGroup.Root (radiogroup):** Groups the items as one set of choices.
* **ChoiceGroup.Item (radio):** Named by its text. A hidden native radio beside it submits the value.
* **Decoration (aria-hidden):** The sliding pill and item icons are hidden from screen readers.
* **Selected (aria-checked):** The selected item sits on a pill or tinted chip, and its text darkens.
* **Disabled Item (disabled):** Makes the option unavailable and dims it to 32% opacity.
* **Target Size (28 to 48px):** Small items sit close to the WCAG 2.2 minimum. Avoid them for primary controls.

### Keyboard

* **Move into the Group (Tab):** Moves focus onto the checked item. The group is one tab stop.
* **Move out of the Group (Shift+Tab):** Moves focus out of the group.
* **Select the Next Item (Right Arrow or Down Arrow):** Moves focus to the next item and selects it, wrapping at the end.
* **Select the Previous Item (Left Arrow or Up Arrow):** Moves focus to the previous item and selects it, wrapping at the start.

### Motion

Under `prefers-reduced-motion: reduce`, the pill moves without sliding and items don't scale when pressed.

### Your Responsibilities

* **Name the Group (aria-labelledby):** Use a `Field.Label` in a `Field.Root`, `aria-label`, or a visible question such as "Amount".
* **Give Every Item Text:** Item icons are hidden, so an icon-only item has no accessible name.

## Related

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

Use for one choice in a form.

[Tabs](/docs/components/tabs)

Use for switching between panels.

[Select](/docs/components/select)

Use for longer lists.

[Choicebox](/docs/components/choicebox)

Use for options with descriptions.

[Dashboards](/docs/patterns/dashboards)

Covers filters above charts.
