# 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 choicebox is a tile form of a radio, checkbox, or button, with an optional icon, a title, and a description.

Use it when each option needs more explanation than a label. Name each group with the question it answers.

## 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`, or `large`. It defaults to `medium`.

```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: '6',
    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 instead of holding a 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)

## Guidelines

TODO: Write guidelines for Choicebox.