RadioGroup
One choice out of a few options that are all visible, as plain items or as choice cards.
A radio group asks for exactly one choice and shows every option at once, so the reader can compare them. Use it for up to about six options; for more, or when the options need no comparison, a select takes less room. A group without a choice yet has no selected item; once chosen, the reader cannot clear it, only change it.
// apps/docs/examples/ui/radio-group.tsx'use client';
import {useState} from 'react';
import { Field, FieldContent, FieldDescription, FieldLabel, FieldLegend, FieldSet, FieldTitle,} from '@workspace/active-ui/components/primitives/field';import { RadioGroup, RadioGroupItem,} from '@workspace/active-ui/components/primitives/radio-group';
const PLANS = [ { value: 'monthly', title: 'Monthly', description: 'Contributions are collected on the first working day.', }, { value: 'quarterly', title: 'Quarterly', description: 'Four collections a year, in January, April, July and October.', }, { value: 'yearly', title: 'Yearly', description: 'One collection in January.', },];
/** * One choice out of a few, all visible: plain items beside their labels, and * choice cards with a description. The group is a `FieldSet` named by its * legend; the arrow keys move between the items. */export default function RadioGroupExample() { const [plan, setPlan] = useState('monthly'); return ( <div className="grid w-full max-w-md gap-8"> <FieldSet> <FieldLegend variant="label">Statement language</FieldLegend> <RadioGroup defaultValue="en" aria-label="Statement language"> {[ ['en', 'English'], ['nl', 'Dutch'], ['de', 'German'], ].map(([value, label]) => ( <Field key={value} orientation="horizontal"> <RadioGroupItem value={value} id={`language-${value}`} /> <FieldLabel htmlFor={`language-${value}`}>{label}</FieldLabel> </Field> ))} </RadioGroup> </FieldSet>
<FieldSet> <FieldLegend variant="label">Collection</FieldLegend> <RadioGroup value={plan} onValueChange={(value) => setPlan(value as string)} aria-label="Collection" > {PLANS.map((option) => ( <FieldLabel key={option.value} htmlFor={`plan-${option.value}`}> <Field orientation="horizontal"> <RadioGroupItem value={option.value} id={`plan-${option.value}`} /> <FieldContent> <FieldTitle>{option.title}</FieldTitle> <FieldDescription>{option.description}</FieldDescription> </FieldContent> </Field> </FieldLabel> ))} </RadioGroup> <p className="text-muted-foreground text-sm">Chosen: {plan}</p> </FieldSet> </div> );}Usage#
import { Field, FieldLabel,} from '@workspace/active-ui/components/primitives/field';import { RadioGroup, RadioGroupItem,} from '@workspace/active-ui/components/primitives/radio-group';
<RadioGroup defaultValue="monthly" aria-label="Collection"> <Field orientation="horizontal"> <RadioGroupItem value="monthly" id="monthly" /> <FieldLabel htmlFor="monthly">Monthly</FieldLabel> </Field> <Field orientation="horizontal"> <RadioGroupItem value="yearly" id="yearly" /> <FieldLabel htmlFor="yearly">Yearly</FieldLabel> </Field></RadioGroup>;Anatomy#
Radio: the value and the keyboard.Group valueandon(controlled) orValue Change default;Value namefor a native form. It lays out its children in a grid with a gap.Radio: one option, by itsGroup Item value. The circle fills when it is chosen.Labels and descriptions come from Field: a
Fieldbeside each item, or a whole choice card, as in the example.Label
What your application provides#
A name for the group: a
Fieldwith aSet Fieldaround it, plusLegend aria-orlabel aria-on the group itself.labelledby A label for every item.
The value.
onreports theValue Change valueof the chosen item, untyped unless you give the group a type: narrow it to the values you offer.
Accessibility and keyboard#
The group is one tab stop:
Tabenters it on the chosen item (or the first), the arrow keys move to and choose the next or previous item, andTableaves it.Each item is a
role="radio"button witharia-.checked A disabled item (
disabledon the item) is skipped;disabledon the group disables them all.
API#
RadioGroup#
Import from @workspace/
All props come from the Base UI part this component is built on.
Props
- Type
any
The controlled value of the radio item that should be currently selected.
To render an uncontrolled radio group, use the default prop instead.
- Type
any
The uncontrolled value of the radio button that should be initially selected.
To render a controlled radio group, use the value prop instead.
- Type
boolean- Default
false
Whether the component should ignore user interaction.
- Type
string
Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form.
- Type
string
Identifies the field when a form is submitted.
- Type
boolean- Default
false
Whether the user should be unable to select a different radio button in the group.
- Type
boolean- Default
false
Whether the user must choose a value before submitting a form.
- Type
Ref<HTMLInputElement>
A ref to access the hidden input element.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Events
Called by the component when something happens.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
RadioGroupItem#
Import from @workspace/
All props come from the Base UI part this component is built on.
Props
- Type
any
The unique identifying value of the radio in a group.
- Type
boolean
Whether the component should ignore user interaction.
- Type
boolean
Whether the user should be unable to select the radio button.
- Type
boolean
Whether the user must choose a value before submitting a form.
- Type
Ref<HTMLInputElement>
A ref to access the hidden input element.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
This page adapts the Radio Group documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.