# Radio Group

A set of checkable buttons where only one can be selected at a time.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<ComponentPreview name="radio-group" title="radio-group.tsx">
<Component />
</ComponentPreview>

Radio Group is a set of mutually exclusive options. Only one item can be selected at a time, and the group manages focus with arrow keys.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
~~~bash
npx frakment add radio-group
~~~
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="radio-group" title="components/ui/radio-group.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

~~~tsx title="radio-group.tsx"
import { Label } from "@/components/ui/label";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
<DocsBaseSwitcher base="web" component="radio-group" className="mb-6" />
~~~

~~~tsx
<RadioGroup defaultValue="comfortable">
  <div className="flex items-center gap-3">
    <RadioGroupItem value="default" id="r1" />
    <Label htmlFor="r1">Default</Label>
  </div>
  <div className="flex items-center gap-3">
    <RadioGroupItem value="comfortable" id="r2" />
    <Label htmlFor="r2">Comfortable</Label>
  </div>
</RadioGroup>
~~~

## Composition [#composition]

```text
RadioGroup
└── RadioGroupItem
```

## Examples [#examples]

### With description [#with-description]

Compose `Field`, `FieldContent`, and `FieldDescription` for helper text under each option.

<ComponentPreview name="radio-group-description" title="radio-group-description.tsx" src="examples/radio-group-description.tsx" previewClassName="h-auto py-8">
<r />
</ComponentPreview>

### Choice card [#choice-card]

Wrap each option in `FieldLabel` to make the entire card clickable.

<ComponentPreview name="radio-group-choice-card" title="radio-group-choice-card.tsx" src="examples/radio-group-choice-card.tsx" previewClassName="h-auto py-8">
<l />
</ComponentPreview>

### Fieldset [#fieldset]

Use `FieldSet` and `FieldLegend` for a labelled group.

<ComponentPreview name="radio-group-fieldset" title="radio-group-fieldset.tsx" src="examples/radio-group-fieldset.tsx" previewClassName="h-auto py-8">
<h />
</ComponentPreview>

### Disabled [#disabled]

<ComponentPreview name="radio-group-disabled" title="radio-group-disabled.tsx" src="examples/radio-group-disabled.tsx" previewClassName="h-auto py-8">
<d />
</ComponentPreview>

### Invalid [#invalid]

Mark each item with `aria-invalid` and its `Field` wrapper with `data-invalid`.

<ComponentPreview name="radio-group-invalid" title="radio-group-invalid.tsx" src="examples/radio-group-invalid.tsx" previewClassName="h-auto py-8">
<o />
</ComponentPreview>

## In Context [#in-context]

### Plan selector [#plan-selector]

<ComponentPreview name="radio-group-plan" title="radio-group-plan.tsx" src="examples/radio-group-plan.tsx">
<RadioGroupPlan />
</ComponentPreview>

## API Reference [#api-reference]

### RadioGroup [#radiogroup]

<PropsTable rows={[{"name":"value","type":"string","description":"Controlled selected value."},{"name":"defaultValue","type":"string","description":"Initial selected value when uncontrolled."},{"name":"onValueChange","type":"function","description":"Called when the selection changes."},{"name":"disabled","type":"boolean","default":"false","description":"Disable the entire group."},{"name":"orientation","type":"horizontal | vertical","default":"vertical","description":"Arrow key navigation axis."}]} />

### RadioGroupItem [#radiogroupitem]

<PropsTable rows={[{"name":"value","type":"string","description":"Unique value returned when this item is selected."},{"name":"disabled","type":"boolean","default":"false","description":"Prevent selection."}]} />

## Controlled [#controlled]

```tsx
const [value, setValue] = React.useState("")
<RadioGroup value={value} onValueChange={setValue}>{/* ... */}</RadioGroup>
```

## Keyboard [#keyboard]

| Key | Action |
| :-- | :-- |
| `Space` | Select the focused option |
| `↑` / `↓` | Move between options |

## Data Attributes [#data-attributes]

| Attribute | Values |
| :-- | :-- |
| `data-slot` | `radio-group`, `radio-group-item` |
| `data-state` | `checked` \| `unchecked` |
| `data-disabled` | `true` |
| `data-orientation` | `horizontal` \| `vertical` |

## Accessibility [#accessibility]

- Follows the WAI-ARIA radio group pattern.
- Arrow keys move the selection within the group.
- Each item must have a matching `Label` with `htmlFor`.
- Invalid state is conveyed via `aria-invalid` on the item and `data-invalid` on the wrapper.

## Best Practices [#best-practices]

- **Use for exclusive choices.** Independent toggles belong in Checkbox.
- **Always set a default.** An empty radio group leaves the user unsure of the starting state.
- **Stack vertically for forms.** Horizontal layouts are hard to read past three options.
- **Pair with a visible label.** Every option needs a matching `Label htmlFor`.
## Related Components [#related-components]

- [Checkbox](/docs/components/web/checkbox) — multiple choice
- [Select](/docs/components/web/select) — compact single choice
- [Field](/docs/components/web/field) — label + error