iconiq
—Open GitHub

Radio Group

Single-select option group for mutually exclusive choices.

Installation

npx shadcn@latest add @iconiq/r-radio-group

Props

Radio option shape

Options are plain objects consumed by the RadioGroup component.

valuestring

Required

Unique identifier for the option and the selected value reported through onChange.
labelstring

Required

Primary line shown for the option.
descriptionstring
Optional secondary line shown below the label with reduced emphasis.

RadioGroup

Single-choice selector with the same Iconiq row motion layered over Radix UI primitives.

options{ value: string; label: string; description?: string }[]

Required

Available choices in display order.
defaultValuestring
Initial uncontrolled selection. If omitted or invalid, the component falls back to the first option.
valuestring
Controlled selected value. When provided, parent state owns selection and the component only reports changes.
onChange(value: string) => void
Called whenever a user selects a row.
namestring
Shared radio input name. If omitted, the component generates one per instance.
layoutIdstring
Motion layout id used by the selected row highlight. Override it only when you want to intentionally share that highlight between groups.
"aria-label"string
Accessible name for the radiogroup. Provide this or aria-labelledby so assistive tech can announce the set clearly.
"aria-labelledby"string
ID of external text that labels the radiogroup. Use this instead of aria-label when visible copy already exists.
classNamestring
Merged onto the root wrapper for spacing or sizing adjustments.

If options is empty, the component returns null rather than rendering an empty radiogroup.

In uncontrolled mode, the selected value normalizes back to the first available option if the current selection disappears from the options array.

Motion and accessibility

The component wraps native radio inputs in an animated label shell so keyboard, form, and screen-reader behavior stay intact.

Built on Radix RadioGroup.Root and RadioGroup.Item while preserving the same staggered row entrance, shared layout highlight, and spring-loaded ring and dot animation.

The root keeps radiogroup semantics and each input supports Arrow keys plus Home and End navigation with a single tab stop inside the set.

Each instance gets its own highlight layoutId by default, so separate groups on the same page do not animate across each other unless you opt into a shared layoutId.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @radix-ui/react-radio-group, motion.

Installs a Radix radio group with the same options, value, defaultValue, onChange, name, and layoutId API as the Base UI version.

Keeps the exact same row entrance, active highlight, and ring-and-dot motion used by the original radio group component.

The generated registry file is /r/r-radio-group.json.