# RadioGroup

> A labelled set of mutually exclusive options, with list and card layouts.

Category: Forms · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/radio-group

Use RadioGroup when exactly one option must be chosen from a small, visible set, especially when options need explanation. The card variant suits plan or workflow choices with descriptions. For long lists, use Select or NativeSelect; for two-state settings that apply immediately, use Switch.

## Import

```tsx
import { RadioGroup, Radio } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Radio, RadioGroup } from '@bindshq/stance-react';

export function Basic() {
  return (
    <RadioGroup label="Signing order" defaultValue="parallel">
      <Radio
        value="parallel"
        label="Any order"
        description="Everyone receives the request at once."
      />
      <Radio
        value="sequential"
        label="One after another"
        description="Each signer is notified when the previous one finishes."
      />
    </RadioGroup>
  );
}
```

### Card variant

```tsx
import { Radio, RadioGroup } from '@bindshq/stance-react';

export function Cards() {
  return (
    <RadioGroup
      label="Deployment method"
      variant="card"
      defaultValue="relay"
      orientation="horizontal"
    >
      <Radio
        value="relay"
        label="Exchange relay"
        description="Signatures are applied server-side to every outgoing email."
      />
      <Radio
        value="addin"
        label="Outlook add-in"
        description="Users pick their signature while composing."
      />
      <Radio
        value="manual"
        label="Manual install"
        description="Users copy the HTML into their mail client."
      />
    </RadioGroup>
  );
}
```

### Horizontal

```tsx
import { Radio, RadioGroup } from '@bindshq/stance-react';

export function Horizontal() {
  return (
    <RadioGroup label="Logo size" orientation="horizontal" defaultValue="md" size="sm">
      <Radio value="sm" label="Small" />
      <Radio value="md" label="Medium" />
      <Radio value="lg" label="Large" />
    </RadioGroup>
  );
}
```

### Validation and disabled options

```tsx
import { Radio, RadioGroup } from '@bindshq/stance-react';

export function Validation() {
  return (
    <RadioGroup label="Plan" required error="Choose a plan to continue">
      <Radio value="starter" label="Starter" />
      <Radio value="team" label="Team" />
      <Radio value="enterprise" label="Enterprise" description="Contact sales" disabled />
    </RadioGroup>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| RadioGroup | `label` (required) | `ReactNode` | None | Group label, rendered as the legend. |
| RadioGroup | `value` | `string \| null` | None | Controlled value. |
| RadioGroup | `defaultValue` | `string \| null` | `null` | Initial value. |
| RadioGroup | `onValueChange` | `(value: string) => void` | None | Called when the selection changes. |
| RadioGroup | `name` | `string` | None | Form field name; generated if omitted. |
| RadioGroup | `variant` | `'default' \| 'card'` | `'default'` | List of radios or selectable cards. |
| RadioGroup | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout of the options. |
| RadioGroup | `description / error` | `ReactNode` | None | Help text and error message. |
| RadioGroup | `required / disabled` | `boolean` | `false` | Required indicator and native required; disable all options. |
| Radio | `value` (required) | `string` | None | The option value. |
| Radio | `label` | `ReactNode` | None | Option label. |
| Radio | `description` | `ReactNode` | None | Supporting text, linked via aria-describedby. |
| Radio | `disabled` | `boolean` | None | Disables this option. |

## Accessibility

- Built from native radio inputs sharing one name, so arrow keys move selection and Tab enters on the checked option, exactly as browsers implement it.
- The fieldset carries role="radiogroup" with the legend as its name; error and required state are exposed on the group.
- Card options show focus on the whole card and selection with both border weight and the radio dot, not colour alone.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Moves into the group (to the checked option) and out of it. |
| `ArrowDown` `ArrowRight` | Selects the next option. |
| `ArrowUp` `ArrowLeft` | Selects the previous option. |
| `Space` | Selects the focused option if none is selected. |

## Guidelines

**Do**

- Pre-select the safest or most common option when there is one.
- Keep options to about seven or fewer.

**Don’t**

- Use radios for a single on/off choice; use Checkbox or Switch.

## Related

- https://stanceui.com/components/checkbox-group
- https://stanceui.com/components/select
- https://stanceui.com/components/switch