Next.js Radio Group with the App Router

Drivn installs through a small CLI that writes component source directly into your repository — there is no runtime package to version-lock. From the root of your Next.js 16 project run npx drivn add radio-group. The Radio Group imports nothing past React and the local cn utility, so the CLI writes a single radio-group.tsx file and leaves the rest of your tree untouched. The CLI reference documents every flag, including targeting a custom directory or installing several components at once. After install you own the file, and future Drivn releases will not overwrite it — commit it for a clean baseline before wiring it into a form. If the same screen collects other fields, pair it with the Drivn Input and Label from the same install.

Because the group holds its selected value in state, radio-group.tsx carries a 'use client' directive and renders inside a client boundary. The quickest shape is uncontrolled: pass defaultValue to the root and a value plus label to each RadioGroup.Item, and the component tracks the choice internally. One import covers the root and the item because they are joined with Object.assign. In a Next.js App Router page, keep the surrounding page a Server Component and mount the group inside a small client component — the 'use client' boundary belongs to whoever owns interactive state, not the whole route. Reach for controlled mode only when the parent needs to read or set the value as the user clicks. Each item accepts an optional description for a card-style option with a muted second line.

When the parent needs the current selection — to gate a submit button, to branch the UI, or to post the value to a route handler — switch to controlled mode. Hold the value in React.useState, pass it as the value prop, and update it from onValueChange. The root detects the controlled prop (it checks controlledValue !== undefined) and defers to your state instead of its internal copy, so the parent becomes the single source of truth for the choice. From there you can send the value to a Server Action, disable a Button until a tier is chosen, or render a different panel per selection. The defaultValue and value props are mutually exclusive — pass defaultValue for a set-and-forget group, value plus onValueChange when the parent must read every change.

The root owns one piece of state — the selected value — and shares it through context. It initializes React.useState(defaultValue ?? ''), computes isControlled from whether a value prop was passed, and derives current as the controlled value when present or the internal state otherwise. The onSelect callback sets internal state only in uncontrolled mode and always fires onValueChange, so both modes flow through the same handler. That value, the onSelect function, the disabled flag, and the variant go into the context provider, and each Item reads them with a useRadioGroup() hook. An item is checked when ctx.value === value, and clicking its hidden <input type="radio"> calls ctx.onSelect(value). One boolean of controlled-vs-uncontrolled logic, one context read per item — the whole state machine reads top to bottom in the file you own.

Every class the group renders lives in one styles object at the top of the file you own. The indicator shape is a variant prop on the root — circle (the default) applies rounded-full, square applies rounded-[4px] — and the inner dot mirrors the shape through the indicators map. Switch the group to a row by passing orientation="horizontal", which adds styles.horizontal (flex-row gap-4) to the flex flex-col gap-3 base. The checked indicator reads bg-foreground and the labels read Tailwind tokens like text-foreground and text-muted-foreground, so changing those tokens in theming re-themes every radio group for dark and light mode at once. Disable the whole set with the disabled prop on the root, or one option with disabled on a single Item. For copy-paste layouts and stateful patterns see the Radio Group examples.