RadioGroup
Radio groups let people choose one option from a short visible set through options or RadioGroupItem composition.
Overview and decision boundary
Use RadioGroup when one choice must be selected from a short, visible set.
Do not use RadioGroup for large searchable sets; use Select or a future picker.
Preview
Visibility
Choose who can access this project.
Select the visibility that matches the project.
import { RadioGroup, RadioGroupItem } from '@nerio-ui/ui/client';<RadioGroup label="Visibility" name="visibility" defaultValue="team"> <RadioGroupItem value="private" description="Only you can access it.">Private</RadioGroupItem> <RadioGroupItem value="team">Team</RadioGroupItem></RadioGroup>// Options API remains available for concise data-driven groups.<RadioGroup label="Visibility" options={[{ label: "Private", value: "private" }]} />Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm dlx nerio add radio-groupimport { RadioGroup, RadioGroupItem } from '@nerio-ui/ui/client';Usage
import { RadioGroup, RadioGroupItem } from '@nerio-ui/ui/client';<RadioGroup label="Visibility" name="visibility" defaultValue="team"> <RadioGroupItem value="private" description="Only you can access it.">Private</RadioGroupItem> <RadioGroupItem value="team">Team</RadioGroupItem></RadioGroup>// Options API remains available for concise data-driven groups.<RadioGroup label="Visibility" options={[{ label: "Private", value: "private" }]} />Variants
| Variant | Use |
|---|---|
Default | Stacked radio options for small sets. |
Invalid | Connects group validation state and message. |
Disabled | Prevents changes for the group or an individual option. |
Anatomy
| Slot | Purpose |
|---|---|
root | Field wrapper with label, description, group, and message. |
label | Visible group label connected through aria-labelledby. |
description | Optional group context connected through aria-describedby. |
group | Base UI radiogroup that manages one selected value. |
option | Clickable option row with control and text. |
control | Base UI radio control. |
indicator | White selected-state dot on brand surface. |
option-content | Visible option label and optional description. |
option-label | Visible label content for one selectable option. |
option-description | Optional supporting text for one selectable option. |
message | Optional helper or validation message. |
States
| State | Behavior |
|---|---|
Checked | One option is selected. |
Disabled | The whole group or individual options can be disabled. |
Read-only | The selected option remains visible without accepting changes. |
Invalid | Connects validation message and invalid state. |
Motion
- State changes should use shared motion tokens and preserve reduced-motion behavior.
Accessibility
- Uses Base UI Radio Group and Radio primitives for keyboard behavior.
- Associates the visible group label with aria-labelledby.
- Connects description and message text through aria-describedby.
- Supports options and RadioGroupItem composition with one shared Base UI state model.
- Supports disabled options, required, read-only, invalid, controlled, and uncontrolled values.
- Validation messages use role="alert" only when invalid is true.
API
| Prop | Purpose |
|---|---|
value / defaultValue / onValueChange | Controlled and uncontrolled value APIs for one selected option. |
options | Concise API for data-driven sets with label, value, description, and disabled. |
children / RadioGroupItem | Composition API for rich option content and explicit source control. |
onValueChange | Receives value and Base UI event details; onChange remains compatible. |
label / description / message | Text slots wired to aria-labelledby and aria-describedby. |
invalid | Sets invalid state on the group and message. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | radio-group installs 5 Tailwind-first source files into the configured components directory. |
Base UI | radio-group, radio |
Registry dependencies | form-message |
Package dependencies | @base-ui/react, clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use RadioGroup when one choice must be selected from a short, visible set.
Do / do not
Do
Use options for concise data-driven sets and RadioGroupItem composition for richer or conditional option content.
Do not
Use RadioGroup for large searchable sets; use Select or a future picker.
Related components
Tokens
These are the primary customization points. Override semantic or component tokens instead of changing component source.
| Token | Purpose |
|---|---|
--n-radio-size | Public customization point for this component contract. |
--n-radio-dot-size | Public customization point for this component contract. |
--n-radio-radius | Public customization point for this component contract. |
--n-input-border | Public customization point for this component contract. |
--n-input-border-hover | Public customization point for this component contract. |
--n-input-border-danger | Public customization point for this component contract. |
--n-color-action-primary | Public customization point for this component contract. |
--n-field-gap | Public customization point for this component contract. |
--n-focus-ring | Public customization point for this component contract. |