Skip to content

Radio Group

⋯

Radio Group composes Base UI selection behavior with the Radio Button design. Each option has a 20px control, a label, and optional supporting text. Radio Group renders in Light and Dark. See Light and Dark.

Import RadioGroup from @nesra/ui/radio-group or the package root. Compose its parts with RadioGroup.Label, RadioGroup.Options, and RadioGroup.Item. Option text uses RadioGroup.Item.Label and RadioGroup.Item.Description. A named group submits its selected string value with a form.

import { RadioGroup } from "@nesra/ui/radio-group";
export function PlanChoice() {
return (
<RadioGroup name="plan" defaultValue="standard">
<RadioGroup.Label>Plan</RadioGroup.Label>
<RadioGroup.Options>
<RadioGroup.Item value="standard">
<RadioGroup.Item.Label>Standard</RadioGroup.Item.Label>
</RadioGroup.Item>
<RadioGroup.Item value="pro">
<RadioGroup.Item.Label>Pro</RadioGroup.Item.Label>
</RadioGroup.Item>
</RadioGroup.Options>
</RadioGroup>
);
}
RadioGroup
├── RadioGroup.Label
├── RadioGroup.Description (optional)
├── RadioGroup.Options
│ └── RadioGroup.Item (one per option)
│ ├── RadioGroup.Item.Label
│ └── RadioGroup.Item.Description (optional)
└── RadioGroup.Error (when invalid)
Delivery speed

A disabled option cannot be selected.

Delivery speed

Choose one option.

orientation="horizontal" places options in a row and lets them wrap when space is limited.

Export format

Use value and onValueChange when application state owns the selection.

Delivery speed

Selected: standard

invalid marks the group invalid. Place RadioGroup.Error after the options to display and associate an error. The example clears the external invalid state when a choice is made.

Export format
Choose an export format.

disabled on RadioGroup prevents selection of every option, including a previously selected one.

Delivery speed

name supplies the submitted field name. required prevents submission until an option is chosen.

Delivery speed

Radio Group uses semantic roles, so it follows the nearest .dark or data-theme="dark" ancestor with no extra props. The roles match the Figma .Radio and Radio Button component bindings.

State Control fill Control border Dot Option label Option description
Unselected foundation-bg-neutral stroke-brand-primary — text-body text-support
Selected action-primary-default action-primary-default icon-on-brand text-body text-support
Disabled foundation-bg-disabled stroke-brand-primary icon-disabled text-support text-support

Keyboard focus adds shadow-nesra-focus-ring (Figma Box Shadow/Focus ring) to the focused option only. In Dark, action-primary-default is near white, so the selected control is light with a near-black dot. RadioGroup.Description uses text-support, and RadioGroup.Error uses text-destructive.

  • Give each group a RadioGroup.Label or aria-label, and every option a RadioGroup.Item.Label.
  • RadioGroup.Item.Description describes an option without adding text to its name.
  • Base UI moves focus and selection with arrow keys and skips disabled options. orientation changes layout and the group’s aria-orientation. Arrow keys remain available in both layouts.
  • Supply the invalid state and an error message when validation happens outside the native form. Keep the error copy specific to the group.

Root for one selected value. It renders a Base UI Radio Group and forwards its ref to the radiogroup element.

Prop Type Default Effect
value string — Controls the selected option.
defaultValue string — Initially selects an option without controlling later changes.
onValueChange (value: string, details) => void — Runs when a user changes the selection.
invalid boolean false Marks the group invalid and displays RadioGroup.Error when present.
orientation "vertical" | "horizontal" "vertical" Sets option layout and aria-orientation. Horizontal options wrap.

Other Base UI Radio Group props are forwarded. Set name for form submission, required for native validity, or disabled to prevent selection of every option. disabled defaults to false. form, readOnly, ARIA attributes, className, and inputRef are also available.

Names the group without selecting an option when clicked. Also exported as RadioGroupLabel. Accepts native div props except id, which the group assigns for labeling. Its ref points to the div.

Adds text beneath the group label and to its accessible description. Also exported as RadioGroupDescription. Accepts Base UI Field Description props and forwards its ref to the paragraph.

Lays out the options according to the root’s orientation. Also exported as RadioGroupOptions. Accepts native div props and forwards its ref to the options container.

Selectable option. Also exported as RadioGroupItem.

Prop Type Default Effect
value string — Required value selected and submitted.
disabled boolean false Prevents this option from being selected.
controlRef Ref<HTMLSpanElement> — Points to the visible radio control.
inputRef Ref<HTMLInputElement> — Points to the native radio input.

Accepts native label props and forwards its ref to the wrapping label.

Gives an option its accessible name. Also exported as RadioGroupItemLabel. Its children are required. Accepts native span props and forwards its ref to the span.

Adds supporting text beneath an option label and to its accessible description. Also exported as RadioGroupItemDescription. Accepts native span props and forwards its ref to the span.

Displays a message when the group is invalid and associates it with the group. Place it after the options. Also exported as RadioGroupError.

Prop Type Default Effect
match boolean | keyof ValidityState true when invalid is true Overrides the Base UI Field Error match condition.

Other Base UI Field Error props are forwarded. Its ref points to the error div.

Selected, focused, and disabled visuals use the color tokens, typography, layout, and shape and elevation contracts.