Forms
Radio Group
A set of options where exactly one can be chosen. Items are 20px circles that fill with the primary blue when selected.
import * as RadioGroup from '@statix/ui/radio-group';Playground
<RadioGroup.Root bind:value>
<div class="flex items-center gap-3">
<RadioGroup.Item value="email" id="email" />
<Label for="email">By email</Label>
</div>
<div class="flex items-center gap-3">
<RadioGroup.Item value="post" id="post" />
<Label for="post">By post</Label>
</div>
</RadioGroup.Root>Examples
Basic
Bind the value of the group. Each item has its own Label.
<script lang="ts">
import { Label } from '@statix/ui/label';
import * as RadioGroup from '@statix/ui/radio-group';
let delivery = $state('email');
</script>
<RadioGroup.Root bind:value={delivery} aria-label="Invoice delivery" class="w-fit">
<div class="flex items-center gap-3">
<RadioGroup.Item value="email" id="rg-email" />
<Label for="rg-email" class="font-normal">By email</Label>
</div>
<div class="flex items-center gap-3">
<RadioGroup.Item value="post" id="rg-post" />
<Label for="rg-post" class="font-normal">By post</Label>
</div>
</RadioGroup.Root>With descriptions
Horizontal Fields with FieldContent explain each option.
<script lang="ts">
import * as Field from '@statix/ui/field';
import * as RadioGroup from '@statix/ui/radio-group';
let schedule = $state('night');
</script>
<Field.Set class="w-full max-w-md">
<Field.Legend variant="label">When should we install updates?</Field.Legend>
<RadioGroup.Root bind:value={schedule}>
<Field.Field orientation="horizontal">
<RadioGroup.Item value="night" id="up-night" />
<Field.Content>
<Field.Label for="up-night">At night</Field.Label>
<Field.Description>Between 02:00 and 05:00, after the nightly backup.</Field.Description>
</Field.Content>
</Field.Field>
<Field.Field orientation="horizontal">
<RadioGroup.Item value="manual" id="up-manual" />
<Field.Content>
<Field.Label for="up-manual">Only after I approve them</Field.Label>
<Field.Description>We email you a list and wait for your OK.</Field.Description>
</Field.Content>
</Field.Field>
</RadioGroup.Root>
</Field.Set>Choice cards
Wrap each Field in FieldLabel to turn options into tiles. Good for plans and add-ons with a price.
<script lang="ts">
import * as Field from '@statix/ui/field';
import * as RadioGroup from '@statix/ui/radio-group';
let retention = $state('30');
const options = [
{ value: '14', title: '14 days', description: 'Included in your plan.' },
{ value: '30', title: '30 days', description: '2 € per month.' },
{ value: '90', title: '90 days', description: '5 € per month.' }
];
</script>
<Field.Set class="w-full max-w-md">
<Field.Legend variant="label">Keep backups for</Field.Legend>
<RadioGroup.Root bind:value={retention} class="gap-2">
{#each options as option (option.value)}
<Field.Label for="ret-{option.value}">
<Field.Field orientation="horizontal">
<Field.Content>
<Field.Title>{option.title}</Field.Title>
<Field.Description>{option.description}</Field.Description>
</Field.Content>
<RadioGroup.Item value={option.value} id="ret-{option.value}" />
</Field.Field>
</Field.Label>
{/each}
</RadioGroup.Root>
</Field.Set>Horizontal
Set orientation="horizontal" so arrow keys match the layout, and lay the items out in a row.
<script lang="ts">
import { Label } from '@statix/ui/label';
import * as RadioGroup from '@statix/ui/radio-group';
let interval = $state('yearly');
</script>
<RadioGroup.Root
bind:value={interval}
orientation="horizontal"
aria-label="Billing interval"
class="flex w-fit gap-6"
>
<div class="flex items-center gap-3">
<RadioGroup.Item value="monthly" id="bi-monthly" />
<Label for="bi-monthly" class="font-normal">Monthly</Label>
</div>
<div class="flex items-center gap-3">
<RadioGroup.Item value="yearly" id="bi-yearly" />
<Label for="bi-yearly" class="font-normal">Yearly, 2 months free</Label>
</div>
</RadioGroup.Root>Disabled item
Disable single items and say why in the label.
<script lang="ts">
import { Label } from '@statix/ui/label';
import * as RadioGroup from '@statix/ui/radio-group';
</script>
<RadioGroup.Root value="php83" aria-label="PHP version" class="w-fit">
<div class="flex items-center gap-3">
<RadioGroup.Item value="php83" id="php83" />
<Label for="php83" class="font-normal">PHP 8.3</Label>
</div>
<div class="flex items-center gap-3">
<RadioGroup.Item value="php82" id="php82" />
<Label for="php82" class="font-normal">PHP 8.2</Label>
</div>
<div class="flex items-center gap-3">
<RadioGroup.Item value="php74" id="php74" disabled />
<Label for="php74" class="font-normal">PHP 7.4 (no longer supported)</Label>
</div>
</RadioGroup.Root>Guidelines
Do
- Use a radio group for two to five options that people should compare side by side.
- Preselect the option most people choose.
- Put the price or consequence in the description, not in a tooltip.
Don't
- Don't use a radio group for more than about six options. Use Select.
- Don't use a single radio button. Use Checkbox or Switch.
Accessibility
- The root has role="radiogroup", each item role="radio" with aria-checked.
- Tab moves into the group to the selected item. Arrow keys move and select. Disabled items are skipped.
- Name the group with a FieldLegend in a FieldSet, or aria-label on the root.
- Label each item with <Label for> pointing at its id.
API reference
RadioGroup.Root
renders<div role="radiogroup"> and accepts its attributes| Prop | Type | Default |
|---|---|---|
value bind | string The selected value. | '' |
onValueChange | (value: string) => void Called when the selection changes. | – |
orientation | 'vertical' | 'horizontal' Which arrow keys move between items. Does not change the layout. | 'vertical' |
disabled | boolean Disables every item. | false |
required | boolean Marks the group as required. | false |
name | string Name of the hidden input for form submission. | – |
loop | boolean Arrow keys wrap from last to first. | true |
ref bind | HTMLDivElement | null The rendered element. | – |
class | ClassValue Merged with the default grid gap-3; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="radio-group" | Always present. |
data-orientation | The current orientation. |
RadioGroup.Item
renders<button role="radio"> and accepts its attributes| Prop | Type | Default |
|---|---|---|
value * | string The value this item selects. | – |
disabled | boolean Disables this item. | false |
ref bind | HTMLButtonElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="radio-group-item" | Always present. |
data-state | "checked" or "unchecked". |
data-disabled | Present when disabled. |