Radio Group
A set of checkable buttons (known as radio buttons) where no more than one of the buttons can be checked at a time. Wrap it in Field.Set and Field.Legend to label the group in a form, and set name on RadioGroup.Root.
When to use
- Pick exactly one value from a few fixed options, with every option visible at once.
- Prefer
Selectwhen the set is long, or the form has little space. - Prefer
Checkboxwhen the user picks any number of options. - Prefer
Choicewhen each radio needs a title and a description beside it. See Rich option layout. - Prefer
SegmentedControlfor a few short options in one row, like a view or an environment switch. It builds on the same radio primitive.
List
Use RadioGroup.List and RadioGroup.ListItem when each option needs a description. The list draws one border, and each row tints on hover and when checked.
Cards
Use RadioGroup.Card when each option is a larger block of content, like a plan or an audience. Lay the cards out with a grid on RadioGroup.Root. The checked card gets an accent border and tint.
Rich option layout with Choice
Choice gives each radio option the same indicator-left / title-over-description layout used across mantle, without hand-rolling the flexbox: put RadioGroup.Indicator in Choice.Indicator and the copy in Choice.Content.
Use Choice.Title here, not Choice.Label: the whole RadioGroup.Item is the click target, and a <label htmlFor> can't associate with the radio's role="radio" element. Inside any radio item (Item, ListItem, Card, or Button), Choice.Title and Choice.Description register their ids with the radio. The radio's aria-labelledby points at the title, so the option's accessible name is the title alone, and its aria-describedby points at the description. Without that wiring, role="radio" would flatten both texts into one name. A plain RadioGroup.ItemContent has no title or description part to register, so its text still reads as one name; reach for Choice when the option carries helper text.
Give the RadioGroup itself an accessible name (an aria-label, as above, or a Field.Set / Field.Legend wrapper) so the group is announced as a named set rather than an anonymous radiogroup.
Inside a Field.Set
To bind the same group into a form, wrap it in a Field.Set / Field.Legend: the legend names the set, and keeping aria-label on RadioGroup.Root names the inner radiogroup role too.
With TanStack Form
Use @tanstack/react-form with zod to keep a radio group controlled. Use Field.Set and Field.Legend because the grouped choices answer one shared question.
Composition
RadioGroup supports several layout variants. Compose the parts together to build your own:
Polymorphism
RadioGroup.ItemContent accepts asChild. When true it renders its single child instead of its default <div>, forwarding class names, data-* attributes, and ref onto that child. Reach for it when the title-and-description block beside a radio needs to be a specific element, such as a <p> or a link wrapping the whole content area. Do not reach for a <label htmlFor>: each item is a div[role="radio"], which for cannot bind, and the item's text content is already its accessible name.
The rest of the family deliberately does not take asChild. RadioGroup.Root and List own the group's roving-focus and arrow-key contract; Item, ListItem, and Card each render a div[role="radio"] with its keyboard handling, and Indicator paints the control itself. When the group has a name, Headless UI renders one hidden <input type="radio"> for form submission. For a richer option layout, compose Choice inside RadioGroup.Item (see Rich option layout with Choice) rather than swapping these elements out.
API Reference
RadioGroup.Root
A group of radio items. Manages state so only one item can be selected at a time. Unstyled and simple.
All props from Headless UI RadioGroup, including:
RadioGroup.Item
A simple radio item. The conventional use-case for basic radio options. Must be a child of RadioGroup.Root. Inside Field.Control, the item picks up aria-invalid, aria-errormessage, and aria-describedby. A Choice.Title inside names it through aria-labelledby, and a Choice.Description describes it through aria-describedby.
RadioGroup.Indicator
The selection indicator for any radio item. By default, renders a circle that changes color when checked. Use as a child of RadioGroup.Item, RadioGroup.ListItem, or RadioGroup.Card.
Accepts a render-props function (context) => ReactNode as children for custom indicators. The context includes checked, disabled, focus, hover, and autofocus.
RadioGroup.ItemContent
The content wrapper for any radio item. Wrap labels, descriptions, or other content inside.
All props from div, plus:
RadioGroup.List
A bordered group of radio list items. Use RadioGroup.ListItem as direct children.
Same props as RadioGroup.Root.
RadioGroup.ListItem
A radio list item used inside RadioGroup.List for connected list-style radio options with borders and padding. Inside Field.Control, the item picks up aria-invalid, aria-errormessage, and aria-describedby. A Choice.Title inside names it through aria-labelledby, and a Choice.Description describes it through aria-describedby.
RadioGroup.Card
A radio card item with enhanced styling for card-based radio options. Inside Field.Control, the item picks up aria-invalid, aria-errormessage, and aria-describedby. A Choice.Title inside names it through aria-labelledby, and a Choice.Description describes it through aria-describedby.
RadioGroup.InputSandbox
A sandbox container for input elements composed within radio group items. A click inside it still selects the radio, then focus returns to the input. Keys other than Enter and Tab stop here, so typing does not move the selection. When the item is disabled or unchecked, the input leaves the tab order.