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> );}Composition
Section titled “Composition”RadioGroup├── RadioGroup.Label├── RadioGroup.Description (optional)├── RadioGroup.Options│ └── RadioGroup.Item (one per option)│ ├── RadioGroup.Item.Label│ └── RadioGroup.Item.Description (optional)└── RadioGroup.Error (when invalid)Examples
Section titled “Examples”Basic composition
Section titled “Basic composition”import { RadioGroup } from "@nesra/ui/radio-group";
export function RadioGroupUsageExample() { return ( <RadioGroup defaultValue="standard" name="delivery"> <RadioGroup.Label>Delivery speed</RadioGroup.Label> <RadioGroup.Options> <RadioGroup.Item value="standard"> <RadioGroup.Item.Label>Standard</RadioGroup.Item.Label> </RadioGroup.Item> <RadioGroup.Item value="express"> <RadioGroup.Item.Label>Express</RadioGroup.Item.Label> </RadioGroup.Item> </RadioGroup.Options> </RadioGroup> );}Descriptions and a disabled option
Section titled “Descriptions and a disabled option”A disabled option cannot be selected.
import { RadioGroup } from "@nesra/ui/radio-group";
export function RadioGroupBasicExample() { return ( <RadioGroup defaultValue="standard" name="delivery" required> <RadioGroup.Label>Delivery speed</RadioGroup.Label> <RadioGroup.Description>Choose one option.</RadioGroup.Description> <RadioGroup.Options> <RadioGroup.Item value="standard"> <RadioGroup.Item.Label>Standard</RadioGroup.Item.Label> <RadioGroup.Item.Description>Arrives in five days</RadioGroup.Item.Description> </RadioGroup.Item> <RadioGroup.Item value="express"> <RadioGroup.Item.Label>Express</RadioGroup.Item.Label> <RadioGroup.Item.Description>Arrives tomorrow</RadioGroup.Item.Description> </RadioGroup.Item> <RadioGroup.Item disabled value="pickup"> <RadioGroup.Item.Label>Pickup</RadioGroup.Item.Label> <RadioGroup.Item.Description>Currently unavailable</RadioGroup.Item.Description> </RadioGroup.Item> </RadioGroup.Options> </RadioGroup> );}Horizontal layout
Section titled “Horizontal layout”orientation="horizontal" places options in a row and lets them wrap when space is limited.
import { RadioGroup } from "@nesra/ui/radio-group";
export function RadioGroupHorizontalExample() { return ( <RadioGroup className="mx-auto w-64 max-w-full" name="format" orientation="horizontal"> <RadioGroup.Label className="text-center">Export format</RadioGroup.Label> <RadioGroup.Options className="justify-center"> <RadioGroup.Item value="pdf"> <RadioGroup.Item.Label>PDF</RadioGroup.Item.Label> </RadioGroup.Item> <RadioGroup.Item value="csv"> <RadioGroup.Item.Label>CSV</RadioGroup.Item.Label> </RadioGroup.Item> <RadioGroup.Item value="json"> <RadioGroup.Item.Label>JSON</RadioGroup.Item.Label> </RadioGroup.Item> </RadioGroup.Options> </RadioGroup> );}Controlled selection
Section titled “Controlled selection”Use value and onValueChange when application state owns the selection.
import { useState } from "react";import { RadioGroup } from "@nesra/ui/radio-group";
export function RadioGroupControlledExample() { const [value, setValue] = useState("standard");
return ( <div className="grid gap-nesra-gap-5"> <RadioGroup name="delivery" onValueChange={setValue} value={value}> <RadioGroup.Label>Delivery speed</RadioGroup.Label> <RadioGroup.Options> <RadioGroup.Item value="standard"> <RadioGroup.Item.Label>Standard</RadioGroup.Item.Label> </RadioGroup.Item> <RadioGroup.Item value="express"> <RadioGroup.Item.Label>Express</RadioGroup.Item.Label> </RadioGroup.Item> </RadioGroup.Options> </RadioGroup> <p className="type-nesra-body-small-regular text-nesra-text-support">Selected: {value}</p> </div> );}Validation
Section titled “Validation”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.
import { useState } from "react";import { RadioGroup } from "@nesra/ui/radio-group";
export function RadioGroupValidationExample() { const [value, setValue] = useState("");
return ( <RadioGroup invalid={!value} name="format" onValueChange={setValue} required value={value}> <RadioGroup.Label>Export format</RadioGroup.Label> <RadioGroup.Options> <RadioGroup.Item value="pdf"> <RadioGroup.Item.Label>PDF</RadioGroup.Item.Label> </RadioGroup.Item> <RadioGroup.Item value="csv"> <RadioGroup.Item.Label>CSV</RadioGroup.Item.Label> </RadioGroup.Item> </RadioGroup.Options> <RadioGroup.Error>Choose an export format.</RadioGroup.Error> </RadioGroup> );}Disabled group
Section titled “Disabled group”disabled on RadioGroup prevents selection of every option, including a previously selected one.
import { RadioGroup } from "@nesra/ui/radio-group";
export function RadioGroupDisabledExample() { return ( <RadioGroup defaultValue="standard" disabled name="delivery"> <RadioGroup.Label>Delivery speed</RadioGroup.Label> <RadioGroup.Options> <RadioGroup.Item value="standard"> <RadioGroup.Item.Label>Standard</RadioGroup.Item.Label> </RadioGroup.Item> <RadioGroup.Item value="express"> <RadioGroup.Item.Label>Express</RadioGroup.Item.Label> </RadioGroup.Item> </RadioGroup.Options> </RadioGroup> );}Native form submission
Section titled “Native form submission”name supplies the submitted field name. required prevents submission until an option is chosen.
import { useState, type SubmitEvent } from "react";import { Button } from "@nesra/ui/button";import { RadioGroup } from "@nesra/ui/radio-group";
export function RadioGroupFormExample() { const [submitted, setSubmitted] = useState("");
function handleSubmit(event: SubmitEvent<HTMLFormElement>) { event.preventDefault(); setSubmitted(String(new FormData(event.currentTarget).get("delivery") ?? "")); }
return ( <form className="grid gap-nesra-gap-5" onSubmit={handleSubmit}> <RadioGroup name="delivery" required> <RadioGroup.Label>Delivery speed</RadioGroup.Label> <RadioGroup.Options> <RadioGroup.Item value="standard"> <RadioGroup.Item.Label>Standard</RadioGroup.Item.Label> </RadioGroup.Item> <RadioGroup.Item value="express"> <RadioGroup.Item.Label>Express</RadioGroup.Item.Label> </RadioGroup.Item> </RadioGroup.Options> </RadioGroup> <Button className="w-fit" type="submit"> Submit </Button> {submitted && ( <p className="type-nesra-body-small-regular text-nesra-text-support"> Submitted: {submitted} </p> )} </form> );}Light and Dark
Section titled “Light and Dark”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.
Accessibility
Section titled “Accessibility”- Give each group a
RadioGroup.Labeloraria-label, and every option aRadioGroup.Item.Label. RadioGroup.Item.Descriptiondescribes an option without adding text to its name.- Base UI moves focus and selection with arrow keys and skips disabled options.
orientationchanges layout and the group’saria-orientation. Arrow keys remain available in both layouts. - Supply the
invalidstate and an error message when validation happens outside the native form. Keep the error copy specific to the group.
API reference
Section titled “API reference”RadioGroup
Section titled “RadioGroup”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.
RadioGroup.Label
Section titled “RadioGroup.Label”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.
RadioGroup.Description
Section titled “RadioGroup.Description”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.
RadioGroup.Options
Section titled “RadioGroup.Options”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.
RadioGroup.Item
Section titled “RadioGroup.Item”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.
RadioGroup.Item.Label
Section titled “RadioGroup.Item.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.
RadioGroup.Item.Description
Section titled “RadioGroup.Item.Description”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.
RadioGroup.Error
Section titled “RadioGroup.Error”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.