Forms
Radio group
A set of options where exactly one can be selected. Built on Radix Radio Group with a violet indicator and full keyboard support.
- Source
- src/components/ui/radio.tsx
- Figma
- Radio · state (off, on, disabled) · RadioGroup.
Usage
Included in the GliaKit boilerplate. Import it where you need it:
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio";When to use
- Choosing one option from two to five, when every option should be visible at once.
- Settings where the difference between options needs a sentence of explanation, like billing plans or notification frequency.
- For more than five or six options, use a Select or Combobox to save space.
- For a single on or off setting, use a Switch or Checkbox instead.
- When several options can be picked at once, use checkboxes.
Examples
Option cards
Wrap each item in a label to make the whole card clickable, and highlight the selected one.
Horizontal
Set orientation for left and right arrow keys, and flex-row for the layout.
Disabled
Disable one item, or the whole group. peer-disabled dims the label next to a disabled item.
In a settings card
A controlled group with a Save button that is enabled only when the choice changes.
API reference
RadioGroup
Wraps Radix RadioGroup.Root and accepts all of its props plus native div attributes. Lays items out in a vertical stack with a 10px gap; override with className.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | - | The selected value (controlled). |
| defaultValue | string | - | The initially selected value (uncontrolled). |
| onValueChange | (value: string) => void | - | Called when the selection changes. |
| name | string | - | Form field name, submitted with the selected value. |
| disabled | boolean | false | Disables every item in the group. |
| required | boolean | false | Marks the field as required for native form validation. |
| orientation | "horizontal" | "vertical" | - | Which arrow keys move between items. Does not change the layout; add className="flex-row" for a row. |
| loop | boolean | true | Whether arrow-key navigation wraps from the last item to the first. |
RadioGroupItem
Wraps Radix RadioGroup.Item and accepts all of its props plus native button attributes. Renders a 16px circle with a violet dot when checked. Has no built-in label.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | - | Required. The value this item represents. |
| id | string | - | Set it and point a <label htmlFor> at it so clicking the label selects the item. |
| disabled | boolean | false | Disables this item only. |
Accessibility
- Radix renders role="radiogroup" on the group and role="radio" with aria-checked on each item.
- Tab moves focus into the group (to the checked item) and out again; arrow keys move between items and select them.
- Items have no text of their own: pair each one with a <label htmlFor> matching its id, or give it an aria-label.
- Label the group itself with aria-label or aria-labelledby pointing at a visible heading.
- A 2px focus ring appears on keyboard focus only (focus-visible).