# RadioGroup

Lets you pick a single option from a short list.

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

Figma: [Radio Group](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3506-3363) (`RadioGroup.Root`)

## Overview

Arrow keys move focus and selection together.

## Examples

### Basic

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

function Choice(props: { label: string; value: string }) {
  return (
    <Field.Root>
      <Field.Item>
        <RadioGroup.Item value={props.value} />
        <Field.Label>{props.label}</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}

export function Demo() {
  return (
    <RadioGroup.Root aria-label="Plan" defaultValue="pro">
      <Choice label="Free" value="free" />
      <Choice label="Pro" value="pro" />
      <Choice label="Team" value="team" />
    </RadioGroup.Root>
  )
}
```

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

### Size

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

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

function Choice(props: { label: string; value: string }) {
  return (
    <Field.Root>
      <Field.Item>
        <RadioGroup.Item value={props.value} />
        <Field.Label>{props.label}</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <RadioGroup.Root aria-label={`Plan ${size}`} defaultValue="pro" key={size} size={size}>
          <Choice label={`Free (${size})`} value="free" />
          <Choice label={`Pro (${size})`} value="pro" />
        </RadioGroup.Root>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ display: 'flex', flexWrap: 'wrap', gap: '48' })
}
```

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

### Disabled

Set `disabled` on a `RadioGroup.Item` to disable one option, or on `RadioGroup.Root` to disable the group.

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

function Choice(props: { disabled?: boolean; label: string; value: string }) {
  return (
    <Field.Root>
      <Field.Item>
        <RadioGroup.Item disabled={props.disabled} value={props.value} />
        <Field.Label>{props.label}</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}

export function Demo() {
  return (
    <div {...styles.row()}>
      <RadioGroup.Root aria-label="Plan" defaultValue="pro">
        <Choice label="Free" value="free" />
        <Choice label="Pro" value="pro" />
        <Choice disabled label="Team" value="team" />
      </RadioGroup.Root>
      <RadioGroup.Root aria-label="Disabled plan" defaultValue="pro" disabled>
        <Choice label="Free" value="free" />
        <Choice label="Pro" value="pro" />
      </RadioGroup.Root>
    </div>
  )
}

namespace styles {
  export const row = style({ display: 'flex', flexWrap: 'wrap', gap: '48' })
}
```

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

## Anatomy

Import the component and assemble its parts.

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

<RadioGroup.Root>
  <Field.Root>
    <Field.Item>
      <RadioGroup.Item />
      <Field.Label />
    </Field.Item>
  </Field.Root>
</RadioGroup.Root>
```

## Guidelines

### When to Use

* Pick one of two to five options that people compare side by side.
* Choose a setting with a few fixed values, such as a payout schedule or API key permissions.

### When Not to Use

* Use [Checkbox](/docs/components/checkbox) or [CheckboxGroup](/docs/components/checkbox-group) for several picks, or for a single yes or no.
* Use [Select](/docs/components/select) for more than five options, or when space is tight.
* Use [ChoiceGroup](/docs/components/choice-group) to switch a view or mode, such as 24H and 7D.
* Use [Choicebox](/docs/components/choicebox) when each option needs an icon or a description.
* Use [Switch](/docs/components/switch) for a single setting that applies immediately.

### Ask One Question

Name the group with its question: point `aria-labelledby` at visible text, set `aria-label`, or use a `Fieldset.Legend`.

**Do:** Make every option answer the group's question.

```tsx
/**
 * Do example for "Ask One Question" on the RadioGroup page.
 * Make every option answer the group's question.
 * @module
 */
import { Field, Fieldset, RadioGroup } from '@tempoxyz/ds'

const options = ['Read only', 'Read and write', 'Admin']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Fieldset.Root>
      <Fieldset.Legend>Who can use this key?</Fieldset.Legend>
      <RadioGroup.Root defaultValue="Read only">
        {options.map((option) => (
          <Field.Root key={option}>
            <Field.Item>
              <RadioGroup.Item value={option} />
              <Field.Label>{option}</Field.Label>
            </Field.Item>
          </Field.Root>
        ))}
      </RadioGroup.Root>
    </Fieldset.Root>
  )
}
```

**Don't:** Mix in an option that answers a different question.

```tsx
/**
 * Don't example for "Ask One Question" on the RadioGroup page.
 * Don't mix in an option that answers a different question.
 * @module
 */
import { Field, Fieldset, RadioGroup } from '@tempoxyz/ds'

const options = ['Read only', 'Expires in 30 days', 'Admin']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Fieldset.Root>
      <Fieldset.Legend>Who can use this key?</Fieldset.Legend>
      <RadioGroup.Root defaultValue="Read only">
        {options.map((option) => (
          <Field.Root key={option}>
            <Field.Item>
              <RadioGroup.Item value={option} />
              <Field.Label>{option}</Field.Label>
            </Field.Item>
          </Field.Root>
        ))}
      </RadioGroup.Root>
    </Fieldset.Root>
  )
}
```

### Preselect Only a Safe Default

**Do:** Preselect the option with the least access, such as Read only.

```tsx
/**
 * Do example for "Preselect Only a Safe Default" on the RadioGroup page.
 * Preselect the option with the least access, such as Read only.
 * @module
 */
import { Field, RadioGroup } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <RadioGroup.Root aria-label="Key permissions" defaultValue="read">
      <Field.Root>
        <Field.Item>
          <RadioGroup.Item value="read" />
          <Field.Label>Read only</Field.Label>
        </Field.Item>
      </Field.Root>
      <Field.Root>
        <Field.Item>
          <RadioGroup.Item value="write" />
          <Field.Label>Read and write</Field.Label>
        </Field.Item>
      </Field.Root>
    </RadioGroup.Root>
  )
}
```

**Don't:** Preselect an option that grants more access or moves funds.

```tsx
/**
 * Don't example for "Preselect Only a Safe Default" on the RadioGroup page.
 * Don't preselect an option that grants more access or moves funds.
 * @module
 */
import { Field, RadioGroup } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <RadioGroup.Root aria-label="Key permissions" defaultValue="write">
      <Field.Root>
        <Field.Item>
          <RadioGroup.Item value="read" />
          <Field.Label>Read only</Field.Label>
        </Field.Item>
      </Field.Root>
      <Field.Root>
        <Field.Item>
          <RadioGroup.Item value="write" />
          <Field.Label>Read and write</Field.Label>
        </Field.Item>
      </Field.Root>
    </RadioGroup.Root>
  )
}
```

If no option is safe, leave the group empty, set `required`, and ask for a choice on submit. A group cannot return to empty after a pick. If no choice is a valid answer, add an option such as None.

### Order Options Logically

With no natural order, list the most common option first. Keep the same order wherever the question appears.

**Do:** List time periods in order, from Daily to Monthly.

```tsx
/**
 * Do example for "Order Options Logically" on the RadioGroup page.
 * List time periods in order, from Daily to Monthly.
 * @module
 */
import { Field, RadioGroup } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <RadioGroup.Root aria-label="Payout schedule" defaultValue="weekly">
      {['Daily', 'Weekly', 'Monthly'].map((label) => (
        <Field.Root key={label}>
          <Field.Item>
            <RadioGroup.Item value={label.toLowerCase()} />
            <Field.Label>{label}</Field.Label>
          </Field.Item>
        </Field.Root>
      ))}
    </RadioGroup.Root>
  )
}
```

**Don't:** Mix the order of options that have a sequence.

```tsx
/**
 * Don't example for "Order Options Logically" on the RadioGroup page.
 * Don't mix the order of options that have a sequence.
 * @module
 */
import { Field, RadioGroup } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <RadioGroup.Root aria-label="Payout schedule" defaultValue="weekly">
      {['Monthly', 'Daily', 'Weekly'].map((label) => (
        <Field.Root key={label}>
          <Field.Item>
            <RadioGroup.Item value={label.toLowerCase()} />
            <Field.Label>{label}</Field.Label>
          </Field.Item>
        </Field.Root>
      ))}
    </RadioGroup.Root>
  )
}
```

### Keep Options in a Column

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

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

const options = ['Read only', 'Read and write', 'Admin']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <RadioGroup.Root aria-label="Key permissions" defaultValue="Read only">
      {options.map((option) => (
        <Field.Root key={option}>
          <Field.Item>
            <RadioGroup.Item value={option} />
            <Field.Label>{option}</Field.Label>
          </Field.Item>
        </Field.Root>
      ))}
    </RadioGroup.Root>
  )
}
```

**Don't:** Lay radios out in a wrapping row.

```tsx
/**
 * Don't example for "Keep Options in a Column" on the RadioGroup page.
 * Don't lay radios out in a wrapping row.
 * @module
 */
import { Field, RadioGroup, style } from '@tempoxyz/ds'

const options = ['Read only', 'Read and write', 'Admin']

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <RadioGroup.Root aria-label="Key permissions" defaultValue="Read only" {...styles.row()}>
      {options.map((option) => (
        <Field.Root key={option}>
          <Field.Item>
            <RadioGroup.Item value={option} />
            <Field.Label>{option}</Field.Label>
          </Field.Item>
        </Field.Root>
      ))}
    </RadioGroup.Root>
  )
}

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

### Label Every Option

Set `disabled` on an item only with a nearby reason, such as Requires a verified domain.

**Do:** Wrap each radio in a `Field.Item` with a `Field.Label`, and add a `Field.Description` after it.

```tsx
/**
 * Do example for "Label Every Option" on the RadioGroup page.
 * Wrap each radio in a `Field.Item` with a `Field.Label`, and add a `Field.Description` after it.
 * @module
 */
import { Field, RadioGroup } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <RadioGroup.Root aria-label="Payout schedule" defaultValue="weekly">
      <Field.Root>
        <Field.Item>
          <RadioGroup.Item value="weekly" />
          <Field.Label>Weekly</Field.Label>
        </Field.Item>
        <Field.Description>Every Monday in USDC.</Field.Description>
      </Field.Root>
      <Field.Root>
        <Field.Item>
          <RadioGroup.Item value="monthly" />
          <Field.Label>Monthly</Field.Label>
        </Field.Item>
        <Field.Description>On the first day of each month.</Field.Description>
      </Field.Root>
    </RadioGroup.Root>
  )
}
```

**Don't:** Place plain text beside a radio. A press on it selects nothing.

```tsx
/**
 * Don't example for "Label Every Option" on the RadioGroup page.
 * Don't place plain text beside a radio. A press on it selects nothing.
 * @module
 */
import { RadioGroup, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <RadioGroup.Root aria-label="Payout schedule" defaultValue="weekly">
      <div {...styles.option()}>
        <RadioGroup.Item value="weekly" />
        <span>Weekly: every Monday in USDC.</span>
      </div>
      <div {...styles.option()}>
        <RadioGroup.Item value="monthly" />
        <span>Monthly: on the first day of each month.</span>
      </div>
    </RadioGroup.Root>
  )
}

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

## Content

* **Option labels:** Keep them short and parallel, such as Read only and Read and write. Don't repeat words from the question in every option.

## Accessibility

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

### Semantics

* **RadioGroup.Root (radiogroup):** Groups the radios. Screen readers announce them as one set.
* **RadioGroup.Item (radio):** Announced with its checked state. A hidden native input submits the value under the group's `name`.
* **Disabled Items (aria-disabled):** A disabled item, or every item in a disabled group, stays visible but dimmed.
* **Checked State (dot):** The checked radio fills in and shows a mark, so selection does not rely on color alone.
* **Target Size (16, 20, 24px):** The hit area reaches 10px past each radio, and a label in `Field.Item` adds to it.

### Keyboard

* **Enter the Group (Tab):** Moves focus into the group, onto the checked radio. The group is one Tab stop.
* **Leave the Group (Shift+Tab):** Moves focus out of the group.
* **Select the Next Radio (Down or Right Arrow):** Moves focus to the next radio and selects it, wrapping from last to first.
* **Select the Previous Radio (Up or Left Arrow):** Moves focus to the previous radio and selects it, wrapping from first to last.

Arrow keys skip disabled radios.

### Your Responsibilities

* **Keep Changes Cheap (onValueChange):** Arrow keys select as they move. Avoid costly work on each change.

## Related

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

Use for switching views and modes.

[Choicebox](/docs/components/choicebox)

Use for options with icons or descriptions.

[Select](/docs/components/select)

Use for longer lists.

[Checkbox](/docs/components/checkbox)

Use for independent choices.

[Fieldset](/docs/components/fieldset)

Use for naming a group with a legend.
