# CheckboxGroup

Shares one value array across a group of checkboxes.

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

## Overview

Each [Checkbox](/docs/components/checkbox) inside it joins the array under its `value`.

## Examples

### Basic

```tsx
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

export function Demo() {
  return (
    <CheckboxGroup aria-label="Currencies" defaultValue={['usdc']}>
      {(['USDC', 'USDT', 'EURC'] as const).map((label) => (
        <Field.Root key={label}>
          <Field.Item>
            <Checkbox value={label.toLowerCase()} />
            <Field.Label>{label}</Field.Label>
          </Field.Item>
        </Field.Root>
      ))}
    </CheckboxGroup>
  )
}
```

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

### Parent

For a select-all box, pass every option to `allValues` and add a `Checkbox` with `parent`.

```tsx
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

function Item(props: Checkbox.Props & { label: string }) {
  const { label, ...checkbox } = props

  return (
    <Field.Root>
      <Field.Item>
        <Checkbox {...checkbox} />
        <Field.Label>{label}</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}

export function Demo() {
  return (
    <CheckboxGroup
      allValues={['usdc', 'usdt', 'eurc']}
      aria-label="Currencies"
      defaultValue={['usdc']}
    >
      <Checkbox aria-label="All currencies" parent />
      <Item label="USDC" name="usdc" value="usdc" />
      <Item label="USDT" name="usdt" value="usdt" />
      <Item label="EURC" name="eurc" value="eurc" />
    </CheckboxGroup>
  )
}
```

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

### Disabled

Set `disabled` to disable every checkbox in the group.

```tsx
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

export function Demo() {
  return (
    <CheckboxGroup aria-label="Currencies" defaultValue={['usdc']} disabled>
      {(['USDC', 'USDT', 'EURC'] as const).map((label) => (
        <Field.Root key={label}>
          <Field.Item>
            <Checkbox value={label.toLowerCase()} />
            <Field.Label>{label}</Field.Label>
          </Field.Item>
        </Field.Root>
      ))}
    </CheckboxGroup>
  )
}
```

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

## Anatomy

Import the component and assemble its parts.

```tsx
import { CheckboxGroup, Checkbox } from '@tempoxyz/ds'

<CheckboxGroup>
  <Checkbox />
</CheckboxGroup>
```

## Guidelines

### When to Use

* Choose any number of related options from a short list, such as webhook events or accepted currencies.
* Add a select-all box over that list with a `parent` checkbox.

### When Not to Use

* If only one option can be chosen, use [RadioGroup](/docs/components/radio-group).
* Use [Combobox](/docs/components/combobox) with `multiple` for a long list filtered by typing, such as assets.
* If each option needs an icon or a description, use `Choicebox.CheckboxGroup` from [Choicebox](/docs/components/choicebox).
* Use a single [Checkbox](/docs/components/checkbox) for one independent choice.
* If choices apply immediately, as in a settings list, use a [Switch](/docs/components/switch) for each.

### Name the Group With Its Question

Give the group an `aria-label`, or a `Field.Label` inside a `Field.Root`.

**Do:** Phrase the name as the question the options answer.

```tsx
/**
 * Do example for "Name the Group With Its Question" on the CheckboxGroup page.
 * Phrase the name as the question the options answer.
 * @module
 */
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

const events = ['Payment confirmed', 'Payment failed', 'Refund issued']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root>
      <Field.Label>Which events should this webhook send?</Field.Label>
      <CheckboxGroup defaultValue={['Payment confirmed']}>
        {events.map((event) => (
          <Field.Root key={event}>
            <Field.Item>
              <Checkbox value={event} />
              <Field.Label>{event}</Field.Label>
            </Field.Item>
          </Field.Root>
        ))}
      </CheckboxGroup>
    </Field.Root>
  )
}
```

**Don't:** Use a generic name, such as Options.

```tsx
/**
 * Don't example for "Name the Group With Its Question" on the CheckboxGroup page.
 * Don't use a generic name, such as Options.
 * @module
 */
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

const events = ['Payment confirmed', 'Payment failed', 'Refund issued']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root>
      <Field.Label>Options</Field.Label>
      <CheckboxGroup defaultValue={['Payment confirmed']}>
        {events.map((event) => (
          <Field.Root key={event}>
            <Field.Item>
              <Checkbox value={event} />
              <Field.Label>{event}</Field.Label>
            </Field.Item>
          </Field.Root>
        ))}
      </CheckboxGroup>
    </Field.Root>
  )
}
```

### Stack Options in a Column

**Do:** Keep the default column, so each box lines up with its label.

```tsx
/**
 * Do example for "Stack Options in a Column" on the CheckboxGroup page.
 * Keep the default column, so each box lines up with its label.
 * @module
 */
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

const events = ['Payment confirmed', 'Payment failed', 'Refund issued']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <CheckboxGroup aria-label="Webhook events" defaultValue={['Payment confirmed']}>
      {events.map((event) => (
        <Field.Root key={event}>
          <Field.Item>
            <Checkbox value={event} />
            <Field.Label>{event}</Field.Label>
          </Field.Item>
        </Field.Root>
      ))}
    </CheckboxGroup>
  )
}
```

**Don't:** Run options together in a wrapping row.

```tsx
/**
 * Don't example for "Stack Options in a Column" on the CheckboxGroup page.
 * Don't run options together in a wrapping row.
 * @module
 */
import { Checkbox, CheckboxGroup, Field, style } from '@tempoxyz/ds'

const events = ['Payment confirmed', 'Payment failed', 'Refund issued']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <CheckboxGroup aria-label="Webhook events" defaultValue={['Payment confirmed']}>
      <div {...styles.row()}>
        {events.map((event) => (
          <Field.Root key={event}>
            <Field.Item>
              <Checkbox value={event} />
              <Field.Label>{event}</Field.Label>
            </Field.Item>
          </Field.Root>
        ))}
      </div>
    </CheckboxGroup>
  )
}

namespace styles {
  export const row = style({ columnGap: '12', display: 'flex', flexWrap: 'wrap', rowGap: '8' })
}
```

### Keep the List Short and Ordered

Sort long lists of names alphabetically. If the list no longer fits without scrolling, switch to a [Combobox](/docs/components/combobox) with `multiple`.

**Do:** Order options predictably, such as by payment lifecycle.

```tsx
/**
 * Do example for "Keep the List Short and Ordered" on the CheckboxGroup page.
 * Order options predictably, such as by payment lifecycle.
 * @module
 */
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

const events = ['Payment created', 'Payment confirmed', 'Payment refunded']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <CheckboxGroup aria-label="Webhook events" defaultValue={['Payment confirmed']}>
      {events.map((event) => (
        <Field.Root key={event}>
          <Field.Item>
            <Checkbox value={event} />
            <Field.Label>{event}</Field.Label>
          </Field.Item>
        </Field.Root>
      ))}
    </CheckboxGroup>
  )
}
```

**Don't:** List options in an arbitrary order.

```tsx
/**
 * Don't example for "Keep the List Short and Ordered" on the CheckboxGroup page.
 * Don't list options in an arbitrary order.
 * @module
 */
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

const events = ['Payment refunded', 'Payment created', 'Payment confirmed']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <CheckboxGroup aria-label="Webhook events" defaultValue={['Payment confirmed']}>
      {events.map((event) => (
        <Field.Root key={event}>
          <Field.Item>
            <Checkbox value={event} />
            <Field.Label>{event}</Field.Label>
          </Field.Item>
        </Field.Root>
      ))}
    </CheckboxGroup>
  )
}
```

### Put the Parent Box First

**Do:** Put the `parent` checkbox first, and label it after the set, such as All events.

```tsx
/**
 * Do example for "Put the Parent Box First" on the CheckboxGroup page.
 * Put the `parent` checkbox first, and label it after the set, such as All events.
 * @module
 */
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

const events = ['Payment confirmed', 'Payment failed', 'Refund issued']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <CheckboxGroup
      allValues={events}
      aria-label="Webhook events"
      defaultValue={['Payment confirmed']}
    >
      <Field.Root>
        <Field.Item>
          <Checkbox parent />
          <Field.Label>All events</Field.Label>
        </Field.Item>
      </Field.Root>
      {events.map((event) => (
        <Field.Root key={event}>
          <Field.Item>
            <Checkbox value={event} />
            <Field.Label>{event}</Field.Label>
          </Field.Item>
        </Field.Root>
      ))}
    </CheckboxGroup>
  )
}
```

**Don't:** Put a generic Select all after the options.

```tsx
/**
 * Don't example for "Put the Parent Box First" on the CheckboxGroup page.
 * Don't put a generic Select all after the options.
 * @module
 */
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

const events = ['Payment confirmed', 'Payment failed', 'Refund issued']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <CheckboxGroup
      allValues={events}
      aria-label="Webhook events"
      defaultValue={['Payment confirmed']}
    >
      {events.map((event) => (
        <Field.Root key={event}>
          <Field.Item>
            <Checkbox value={event} />
            <Field.Label>{event}</Field.Label>
          </Field.Item>
        </Field.Root>
      ))}
      <Field.Root>
        <Field.Item>
          <Checkbox parent />
          <Field.Label>Select all</Field.Label>
        </Field.Item>
      </Field.Root>
    </CheckboxGroup>
  )
}
```

### Validate the Group as a Whole

**Do:** If at least one option is required, show one `Field.Error` for the group.

```tsx
/**
 * Do example for "Validate the Group as a Whole" on the CheckboxGroup page.
 * If at least one option is required, show one `Field.Error` for the group.
 * @module
 */
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

const events = ['Payment confirmed', 'Payment failed', 'Refund issued']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root invalid>
      <Field.Label>Which events should this webhook send?</Field.Label>
      <CheckboxGroup defaultValue={[]}>
        {events.map((event) => (
          <Field.Root key={event}>
            <Field.Item>
              <Checkbox value={event} />
              <Field.Label>{event}</Field.Label>
            </Field.Item>
          </Field.Root>
        ))}
      </CheckboxGroup>
      <Field.Error match>Select at least one event</Field.Error>
    </Field.Root>
  )
}
```

**Don't:** Mark each checkbox invalid.

```tsx
/**
 * Don't example for "Validate the Group as a Whole" on the CheckboxGroup page.
 * Don't mark each checkbox invalid.
 * @module
 */
import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'

const events = ['Payment confirmed', 'Payment failed', 'Refund issued']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root>
      <Field.Label>Which events should this webhook send?</Field.Label>
      <CheckboxGroup defaultValue={[]}>
        {events.map((event) => (
          <Field.Root invalid key={event}>
            <Field.Item>
              <Checkbox value={event} />
              <Field.Label>{event}</Field.Label>
            </Field.Item>
            <Field.Error match>Select this event</Field.Error>
          </Field.Root>
        ))}
      </CheckboxGroup>
    </Field.Root>
  )
}
```

## Content

* **Labels:** Write parallel labels, such as Payment confirmed, Payment failed, and Refund issued.
* **Defaults:** Preselect only options that match a saved value or a safe default.

## Accessibility

Wraps related checkboxes in a named `group`. Each checkbox follows the [WAI-ARIA checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).

### Semantics

* **Group (group):** Name it with `aria-label` or a `Field.Label`, or screen readers announce an unnamed group.
* **Checkboxes (checkbox):** Each keeps its own role and state, and adds its `value` to the group. See [Checkbox](/docs/components/checkbox#accessibility).
* **Parent Checkbox (aria-controls):** Points at the checkboxes it controls. Reports a mixed state while only some are checked.
* **Disabled (aria-disabled):** Disables every checkbox and removes them from the tab order.

### Keyboard

* **Move Between Checkboxes (Tab and Shift+Tab):** Moves focus between checkboxes. Each checkbox is its own Tab stop.
* **Toggle a Checkbox (Space):** Toggles the focused checkbox.
* **Toggle the Parent Checkbox (Space):** Checks every option, then clears them. A third press restores the original selection.

### Focus

Focus stays on a parent checkbox when it changes the other options.

### Your Responsibilities

* **Label Every Checkbox:** Give each checkbox its own label.
* **Explain Disabled Options (disabled):** Disables every checkbox. Explain nearby why the options are locked.

## Related

[Checkbox](/docs/components/checkbox)

Use for a single choice.

[Choicebox](/docs/components/choicebox)

Use for options with descriptions.

[Combobox](/docs/components/combobox)

Use for choosing several items from a long list.

[Fieldset](/docs/components/fieldset)

Use for grouping fields under a legend.

[Field](/docs/components/field)

Use for naming the group and showing its error.
