React Radio Group Component Examples

The shortest group that does something useful. defaultValue on the root pre-selects an option; each RadioGroup.Item needs a unique value and a label. Nothing here is controlled — the root keeps the selection in its own React.useState, and the onSelect callback it puts on context updates that state when an item's hidden input fires onChange. The item renders a <label> around both the input and the text-sm font-medium text, so clicking the word "SMS" selects it with no htmlFor or id wiring anywhere in the tree.

This is the right starting shape for a settings row (notification channel, theme preference), a short single-select question, and anything whose value the surrounding page does not need mid-interaction. One detail worth knowing before you drop it in a plain <form>: RadioGroup.Item consumes its value prop rather than forwarding it to the native input, so the checked radio does not carry a useful value through FormData. Read the selection through React instead — onValueChange on the root, which the next example covers. When more than one option can be active at once, the Drivn Checkbox is the component you want.

When the selected value needs to drive surrounding UI — show a different panel per option, enable a button, recompute a price — lift the state into the parent with React.useState and pass value plus onValueChange to the root. The component becomes fully controlled: it renders whatever value the parent holds and reports every change through the callback, so the parent stays the single source of truth. The example below mirrors the selected channel into a line of text, but the same pattern feeds a conditional render, a fetch, or a derived calculation.

The 'use client' directive on this file is necessary because the call site itself runs React.useState — the Radio Group component does not force the boundary, the surrounding component does. onValueChange receives the new value string directly, so there is no event.target unwrapping. Controlled mode is also what the react-hook-form example further down relies on. For a value that the parent only reads at submit time and never mid-interaction, the uncontrolled default group above is the lighter choice.

For a billing plan picker or any option list where each choice needs a supporting line, pass the description prop alongside label. The component stacks the description as a text-sm text-muted-foreground line under the bold label, and the whole two-line block stays inside the clickable <label> so tapping anywhere in the option selects it. This is the cleanest shape for plan tiers, permission levels, and shipping options where the price or detail belongs right under the name.

To turn each option into a bordered card tile, wrap the items in a Drivn Card or pass a className with border and padding utilities through RadioGroup.Item — the className merges via cn() onto the item wrapper. The example below keeps the plain two-line layout. When the built-in label-plus-description block is not enough — say you need a price badge aligned to the right — pass children instead of label/description and render any JSX you want; the component drops the built-in block and renders your content next to the radio. Pair the picker with a Drivn Badge for a "Most popular" marker.

For a compact option row — a yes/no choice, a size selector, a short rating scale — pass orientation="horizontal" on the root. The component swaps its flex container from a column to a row (flex-row gap-4), so the options sit side by side instead of stacked. Pair it with variant="square" to render the radios with a rounded-[4px] frame and a rounded-[2px] inner dot instead of the default circle. A square radio reads as a distinct control while still signalling single-select, which helps in dense panels where circle and square shapes carry meaning.

The variant and orientation props are both read once on the root and shared to every item through context — there is no per-item override, which keeps a group visually consistent. The example below renders a horizontal square group for a t-shirt size picker. Horizontal layout works best with short labels; once an option needs a description line, the vertical default reads more cleanly. For longer option lists that would overflow a row, keep the vertical orientation or switch to the Drivn Select dropdown.

For a radio group inside a real form, wire it to react-hook-form with a Controller and validate the choice with zod. The zod schema marks the field required so a submit with no option selected surfaces an error message. The Controller bridges the form library to the controlled value / onValueChange shape the Radio Group already exposes — field.value flows into value and field.onChange flows into onValueChange, with no adapter code in between.

This is the production shape for a checkout step, a survey question, or any single-select field that must be answered before the form can submit. The zodResolver connects the schema to the form, and the error string renders under the group when validation fails. Because the Radio Group already speaks the controlled-input contract, the Controller wrapper is the only glue needed — the same pattern used for the Drivn Select and Checkbox in forms. See Drivn vs shadcn Radio Group for how the native-input underpinning compares with the Radix-backed alternative.