How to Add a Radio Group to a React App

Before installing Radio Group, confirm your React project has the three things Drivn assumes: Tailwind CSS v4 installed and processing your styles, TypeScript configured (the component ships as a .tsx file), and a @/ path alias pointing at your source directory. If you scaffolded with create-next-app, npm create vite, or npx drivn@latest create, all three are already wired. For a custom setup, check the compilerOptions.paths entry in tsconfig.json; the installation page lists the minimal config. Radio Group imports nothing past React and the cn utility for class merging, so it is a single-file install — no peer components and no runtime package to version-lock. Because it builds on a native <input type="radio"> rather than a headless primitive, it also drops cleanly into an existing form without pulling in a keyboard-navigation or focus-management library.

Run the CLI from your project root to add the Radio Group source file. The command prompts once for your install directory (defaulting to src/components/ui/) and writes a single radio-group.tsx — no other files, because the group has no peer dependencies beyond React and the cn utility. No global config file is created; the result is TypeScript source you edit like any other component. Confirm it landed in your editor, then commit it for a clean baseline. If your project uses a monorepo layout or a non-standard source path, the CLI docs cover the flags for targeting a custom location during install. Because the file is yours after install, future Drivn releases will not overwrite your edits.

Import RadioGroup from your UI directory — one import covers the root and the .Item because they are joined with Object.assign. The quickest shape is uncontrolled: pass defaultValue to the root to pre-select an option, then give each RadioGroup.Item a unique value and a label. The component tracks the choice in its own React.useState, so the surrounding code stays declarative. Because the group holds state, radio-group.tsx carries a 'use client' directive; in a Next.js App Router page keep the route a Server Component and mount the group inside a small client component. Each item wraps a real hidden <input type="radio">, so clicking the label toggles the radio, the browser groups same-name inputs, and the value posts in a plain HTML form — no extra wiring. Add a description prop for a two-line, card-style option.

When the parent needs the current selection — to gate a submit button, branch the UI, or 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 checks controlledValue !== undefined and defers to your state instead of its internal copy, so the parent becomes the single source of truth. The defaultValue and value props are mutually exclusive: pass defaultValue for a set-and-forget group, value plus onValueChange when you must read every change. onValueChange receives the new value string directly, with no event.target unwrapping — drop it into a Button disabled check or a conditional render. For form validation, the same controlled contract wires straight into react-hook-form with a Controller.

Everything visual 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 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 disabled on the root, or a single option with disabled on one Item. For copy-paste layouts and stateful patterns see the Radio Group examples.