# Choicebox

A selectable tile with an optional icon, title, and description.

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

## Overview

A tile form of a radio, checkbox, or button. Pressing anywhere on the tile operates its control.

## Examples

### Basic

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

export function Demo() {
  return (
    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="instant">
      <Choicebox.Radio value="standard">
        <Choicebox.Title>Standard</Choicebox.Title>
        <Choicebox.Description>Settles in one business day</Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio value="instant">
        <Choicebox.Title>Instant</Choicebox.Title>
        <Choicebox.Description>Settles in seconds for a small fee</Choicebox.Description>
      </Choicebox.Radio>
    </Choicebox.RadioGroup>
  )
}
```

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

### Size

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

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

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['small', 'large'] as const).map((size) => (
        <Choicebox.RadioGroup
          aria-label={`Settlement ${size}`}
          defaultValue="instant"
          key={size}
          size={size}
        >
          <Choicebox.Radio value="standard">
            <Choicebox.Title>Standard ({size})</Choicebox.Title>
            <Choicebox.Description>Settles in one business day</Choicebox.Description>
          </Choicebox.Radio>
          <Choicebox.Radio value="instant">
            <Choicebox.Title>Instant ({size})</Choicebox.Title>
            <Choicebox.Description>Settles in seconds for a small fee</Choicebox.Description>
          </Choicebox.Radio>
        </Choicebox.RadioGroup>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({
    alignItems: 'flex-start',
    display: 'grid',
    gap: '24',
    gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 360px)) !custom',
  })
}
```

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

### Disabled

Set `disabled` on a tile to make one option unavailable.

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

export function Demo() {
  return (
    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="instant">
      <Choicebox.Radio value="standard">
        <Choicebox.Title>Standard</Choicebox.Title>
        <Choicebox.Description>Settles in one business day</Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio value="instant">
        <Choicebox.Title>Instant</Choicebox.Title>
        <Choicebox.Description>Settles in seconds for a small fee</Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio disabled value="wire">
        <Choicebox.Title>Wire</Choicebox.Title>
        <Choicebox.Description>Unavailable in your region</Choicebox.Description>
      </Choicebox.Radio>
    </Choicebox.RadioGroup>
  )
}
```

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

### Icon

Add a `Choicebox.Icon` before the title.

```tsx
import { Choicebox } from '@tempoxyz/ds'
import { Bank, CreditCard } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <Choicebox.RadioGroup aria-label="Method" defaultValue="bank">
      <Choicebox.Radio value="bank">
        <Choicebox.Icon>
          <Bank />
        </Choicebox.Icon>
        <Choicebox.Title>Bank transfer</Choicebox.Title>
        <Choicebox.Description>One to two business days</Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio value="card">
        <Choicebox.Icon>
          <CreditCard />
        </Choicebox.Icon>
        <Choicebox.Title>Card</Choicebox.Title>
        <Choicebox.Description>Instant, 2.9% fee</Choicebox.Description>
      </Choicebox.Radio>
    </Choicebox.RadioGroup>
  )
}
```

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

### ButtonGroup

Use `Choicebox.ButtonGroup` and `Choicebox.Button` for tiles that run an action and hold no value.

```tsx
import { Choicebox } from '@tempoxyz/ds'
import { Bank, Wallet } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <Choicebox.ButtonGroup aria-label="Add funds">
      <Choicebox.Button onClick={() => alert('Bank transfer')}>
        <Choicebox.Icon>
          <Bank />
        </Choicebox.Icon>
        <Choicebox.Title>Bank transfer</Choicebox.Title>
        <Choicebox.Description>Opens your deposit details</Choicebox.Description>
      </Choicebox.Button>
      <Choicebox.Button onClick={() => alert('Wallet')}>
        <Choicebox.Icon>
          <Wallet />
        </Choicebox.Icon>
        <Choicebox.Title>From a wallet</Choicebox.Title>
      </Choicebox.Button>
    </Choicebox.ButtonGroup>
  )
}
```

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

### CheckboxGroup

Use `Choicebox.CheckboxGroup` and `Choicebox.Checkbox` for tiles that allow several selections.

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

export function Demo() {
  return (
    <Choicebox.CheckboxGroup aria-label="Alerts" defaultValue={['email']}>
      <Choicebox.Checkbox value="email">
        <Choicebox.Title>Email</Choicebox.Title>
        <Choicebox.Description>Receipts and weekly summaries</Choicebox.Description>
      </Choicebox.Checkbox>
      <Choicebox.Checkbox value="push">
        <Choicebox.Title>Push</Choicebox.Title>
        <Choicebox.Description>Transfers and security events</Choicebox.Description>
      </Choicebox.Checkbox>
    </Choicebox.CheckboxGroup>
  )
}
```

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

## Anatomy

Import the component and assemble its parts.

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

<Choicebox.RadioGroup>
  <Choicebox.Radio>
    <Choicebox.Icon />
    <Choicebox.Title />
    <Choicebox.Description />
  </Choicebox.Radio>
</Choicebox.RadioGroup>

<Choicebox.CheckboxGroup>
  <Choicebox.Checkbox>
    <Choicebox.Icon />
    <Choicebox.Title />
    <Choicebox.Description />
  </Choicebox.Checkbox>
</Choicebox.CheckboxGroup>

<Choicebox.ButtonGroup>
  <Choicebox.Button>
    <Choicebox.Icon />
    <Choicebox.Title />
    <Choicebox.Description />
  </Choicebox.Button>
</Choicebox.ButtonGroup>
```

## Guidelines

### When to Use

* Choose between a few options that each need a description, such as Standard or Instant settlement with time and fee.
* Choose how to start a flow with `Choicebox.ButtonGroup`, such as Bank transfer or From a wallet.
* Choose several described options with `Choicebox.CheckboxGroup`, such as alert channels.

### When Not to Use

* If a label alone tells the options apart, use [RadioGroup](/docs/components/radio-group).
* Use [ChoiceGroup](/docs/components/choice-group) for a short mode switch, such as a chart's time range.
* Use [Select](/docs/components/select) for more options than fit on screen.
* Use [Button](/docs/components/button) for a single action, and [Menu](/docs/components/menu) for actions that need no description.

### Pick the Group by What a Tile Does

* **Radio Tiles (Choicebox.RadioGroup):** Hold one value, such as a settlement speed.
* **Checkbox Tiles (Choicebox.CheckboxGroup):** Hold several values, such as alert channels.
* **Button Tiles (Choicebox.ButtonGroup):** Run an action, such as opening the next step.

### Keep Tile Text Short

The whole tile's text becomes the accessible name, so long text slows every option for screen reader users.

**Do:** Give each tile a title of one to three words and a one-line description.

```tsx
/**
 * Do example for "Keep Tile Text Short" on the Choicebox page.
 * Give each tile a title of one to three words and a one-line description.
 * @module
 */
import { Choicebox, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
      <Choicebox.Radio value="standard">
        <Choicebox.Title>Standard</Choicebox.Title>
        <Choicebox.Description>Settles in one business day</Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio value="instant">
        <Choicebox.Title>Instant</Choicebox.Title>
        <Choicebox.Description>Settles in seconds for a 1% fee</Choicebox.Description>
      </Choicebox.Radio>
    </Choicebox.RadioGroup>
  )
}

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

**Don't:** Repeat the question in each title or write paragraphs in the description.

```tsx
/**
 * Don't example for "Keep Tile Text Short" on the Choicebox page.
 * Don't repeat the question in each title or write paragraphs in the description.
 * @module
 */
import { Choicebox, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
      <Choicebox.Radio value="standard">
        <Choicebox.Title>Standard settlement for this payment</Choicebox.Title>
        <Choicebox.Description>
          Your payment is processed with our standard settlement option, which usually takes about
          one business day depending on your bank.
        </Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio value="instant">
        <Choicebox.Title>Instant settlement for this payment</Choicebox.Title>
        <Choicebox.Description>
          Your payment settles in seconds. A fee applies, shown on the review screen.
        </Choicebox.Description>
      </Choicebox.Radio>
    </Choicebox.RadioGroup>
  )
}

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

### Describe What Sets Each Option Apart

**Do:** Put the deciding difference, such as time or fee, in the same place on every tile.

```tsx
/**
 * Do example for "Keep Tile Text Short" on the Choicebox page.
 * Give each tile a title of one to three words and a one-line description.
 * @module
 */
import { Choicebox, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
      <Choicebox.Radio value="standard">
        <Choicebox.Title>Standard</Choicebox.Title>
        <Choicebox.Description>Settles in one business day</Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio value="instant">
        <Choicebox.Title>Instant</Choicebox.Title>
        <Choicebox.Description>Settles in seconds for a 1% fee</Choicebox.Description>
      </Choicebox.Radio>
    </Choicebox.RadioGroup>
  )
}

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

**Don't:** Write descriptions that vary in structure or leave out the difference.

```tsx
/**
 * Don't example for "Describe What Sets Each Option Apart" on the Choicebox page.
 * Don't write descriptions that vary in structure or leave out the difference.
 * @module
 */
import { Choicebox, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
      <Choicebox.Radio value="standard">
        <Choicebox.Title>Standard</Choicebox.Title>
        <Choicebox.Description>Our most popular option</Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio value="instant">
        <Choicebox.Title>Instant</Choicebox.Title>
        <Choicebox.Description>For a 1% fee, settles in seconds</Choicebox.Description>
      </Choicebox.Radio>
    </Choicebox.RadioGroup>
  )
}

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

### Use Icons on Every Tile or None

**Do:** Add a `Choicebox.Icon` from one icon set to every tile.

```tsx
/**
 * Do example for "Use Icons on Every Tile or None" on the Choicebox page.
 * Add a `Choicebox.Icon` from one icon set to every tile.
 * @module
 */
import { Choicebox, style } from '@tempoxyz/ds'
import { Bank, Wallet } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Choicebox.ButtonGroup aria-label="Add funds" {...styles.group()}>
      <Choicebox.Button>
        <Choicebox.Icon>
          <Bank />
        </Choicebox.Icon>
        <Choicebox.Title>Bank transfer</Choicebox.Title>
        <Choicebox.Description>Arrives in one business day</Choicebox.Description>
      </Choicebox.Button>
      <Choicebox.Button>
        <Choicebox.Icon>
          <Wallet />
        </Choicebox.Icon>
        <Choicebox.Title>From a wallet</Choicebox.Title>
        <Choicebox.Description>Send USDC from any address</Choicebox.Description>
      </Choicebox.Button>
    </Choicebox.ButtonGroup>
  )
}

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

**Don't:** Give icons to only some tiles in a group.

```tsx
/**
 * Don't example for "Use Icons on Every Tile or None" on the Choicebox page.
 * Don't give icons to only some tiles in a group.
 * @module
 */
import { Choicebox, style } from '@tempoxyz/ds'
import { Bank } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Choicebox.ButtonGroup aria-label="Add funds" {...styles.group()}>
      <Choicebox.Button>
        <Choicebox.Icon>
          <Bank />
        </Choicebox.Icon>
        <Choicebox.Title>Bank transfer</Choicebox.Title>
        <Choicebox.Description>Arrives in one business day</Choicebox.Description>
      </Choicebox.Button>
      <Choicebox.Button>
        <Choicebox.Title>From a wallet</Choicebox.Title>
        <Choicebox.Description>Send USDC from any address</Choicebox.Description>
      </Choicebox.Button>
    </Choicebox.ButtonGroup>
  )
}

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

### Preselect a Safe Default

**Do:** Preselect an option only if it costs nothing extra, such as Standard settlement.

```tsx
/**
 * Do example for "Keep Tile Text Short" on the Choicebox page.
 * Give each tile a title of one to three words and a one-line description.
 * @module
 */
import { Choicebox, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
      <Choicebox.Radio value="standard">
        <Choicebox.Title>Standard</Choicebox.Title>
        <Choicebox.Description>Settles in one business day</Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio value="instant">
        <Choicebox.Title>Instant</Choicebox.Title>
        <Choicebox.Description>Settles in seconds for a 1% fee</Choicebox.Description>
      </Choicebox.Radio>
    </Choicebox.RadioGroup>
  )
}

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

**Don't:** Preselect an option with a fee.

```tsx
/**
 * Don't example for "Preselect a Safe Default" on the Choicebox page.
 * Don't preselect an option with a fee.
 * @module
 */
import { Choicebox, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="instant" {...styles.group()}>
      <Choicebox.Radio value="standard">
        <Choicebox.Title>Standard</Choicebox.Title>
        <Choicebox.Description>Settles in one business day</Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio value="instant">
        <Choicebox.Title>Instant</Choicebox.Title>
        <Choicebox.Description>Settles in seconds for a 1% fee</Choicebox.Description>
      </Choicebox.Radio>
    </Choicebox.RadioGroup>
  )
}

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

### Explain Unavailable Options

Leave out options that never apply to the account.

**Do:** If a tile is `disabled`, say why in its description.

```tsx
/**
 * Do example for "Explain Unavailable Options" on the Choicebox page.
 * If a tile is `disabled`, say why in its description.
 * @module
 */
import { Choicebox, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
      <Choicebox.Radio value="standard">
        <Choicebox.Title>Standard</Choicebox.Title>
        <Choicebox.Description>Settles in one business day</Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio disabled value="wire">
        <Choicebox.Title>Wire</Choicebox.Title>
        <Choicebox.Description>Unavailable in your region</Choicebox.Description>
      </Choicebox.Radio>
    </Choicebox.RadioGroup>
  )
}

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

**Don't:** Disable a tile without a reason.

```tsx
/**
 * Don't example for "Explain Unavailable Options" on the Choicebox page.
 * Don't disable a tile without a reason.
 * @module
 */
import { Choicebox, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
      <Choicebox.Radio value="standard">
        <Choicebox.Title>Standard</Choicebox.Title>
        <Choicebox.Description>Settles in one business day</Choicebox.Description>
      </Choicebox.Radio>
      <Choicebox.Radio disabled value="wire">
        <Choicebox.Title>Wire</Choicebox.Title>
        <Choicebox.Description>Settles the same day for a $15 fee</Choicebox.Description>
      </Choicebox.Radio>
    </Choicebox.RadioGroup>
  )
}

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

## Content

* **Descriptions:** Fragments without a trailing period, such as Settles in one business day.
* **Numbers:** Exact fees and times, such as 1% fee, not a small fee.

## Accessibility

Radio tiles follow the [WAI-ARIA radio group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/), and checkbox tiles the [checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).

### Semantics

* **Choicebox.RadioGroup (radiogroup):** Pressing anywhere on a tile selects it.
* **Choicebox.CheckboxGroup (group):** Pressing anywhere on a tile toggles it.
* **Choicebox.ButtonGroup (group):** Each tile is a native button. Enter and Space run it.
* **Name (aria-labelledby):** The tile's title and description together name its control.
* **Icon and Disabled Tiles (aria-disabled):** Icons are hidden from screen readers. A disabled tile marks its control disabled.

### Keyboard

* **Move to a Tile (Tab):** Focuses the checked tile in a radio group. In other groups, each tile is a tab stop.
* **Select the Next or Previous Tile (Arrow keys):** In a radio group, selects the next or previous enabled tile.
* **Toggle a Checkbox Tile (Space):** Toggles a checkbox tile.
* **Activate a Button Tile (Enter or Space):** Activates a button tile.

### Motion

Pressed tiles scale to `scale.press` (0.98), except under `prefers-reduced-motion: reduce`.

### Your Responsibilities

* **Name Each Group (aria-label):** Phrase it as a question, such as "How should this payment settle?"

## Related

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

Use for one choice with short labels.

[CheckboxGroup](/docs/components/checkbox-group)

Use for several choices with short labels.

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

Use for switching a view or mode.

[Fieldset](/docs/components/fieldset)

Use for naming a group with a legend.

[Payments](/docs/patterns/payments)

Covers choosing a funding or settlement method.
