Skip to content
Statix Design System

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

Controls
<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.

When should we install updates?

Between 02:00 and 05:00, after the nightly backup.

We email you a list and wait for your OK.

<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.

Keep backups for
<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
PropTypeDefault
value bindstring

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 bindHTMLDivElement | null

The rendered element.

–
class ClassValue

Merged with the default grid gap-3; yours win.

–
Data attributeMeaning
data-slot="radio-group"Always present.
data-orientationThe current orientation.

RadioGroup.Item

renders <button role="radio"> and accepts its attributes
PropTypeDefault
value * string

The value this item selects.

–
disabled boolean

Disables this item.

false
ref bindHTMLButtonElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–
Data attributeMeaning
data-slot="radio-group-item"Always present.
data-state"checked" or "unchecked".
data-disabledPresent when disabled.