Radio Group React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import RadioGroup from @/components/ui/radio-group.

import { Package, Store, Truck } from "lucide-react"
import { RadioGroup, type RadioOption } from "@/components/ui/radio-group"

const delivery: RadioOption[] = [
  { value: "courier", label: "Home delivery", description: "FedEx, 1-2 days", icon: <Truck />, badge: "$9.99" },
  { value: "locker", label: "Locker", description: "Pick up any time from 3,000 lockers", icon: <Package />, badge: "$5.99" },
  { value: "pickup", label: "In-store pickup", description: "Austin, 2400 S Congress Ave", icon: <Store />, badge: "Free" },
]

export function DeliveryMethod({ value, onChange }: { value: string; onChange: (value: string) => void }) {
  return (
    <RadioGroup
      name="delivery"
      label="Delivery method"
      variant="card"
      options={delivery}
      value={value}
      onValueChange={onChange}
      required
    />
  )
}

// custom content: compose the parts
import { RadioGroupRoot, RadioGroupItem } from "@/components/ui/radio-group"

export function PlanPicker() {
  return (
    <RadioGroupRoot label="Plan" variant="card" columns={2} defaultValue="pro">
      <RadioGroupItem value="free" label="Free" badge="$0" />
      <RadioGroupItem value="pro" label="Pro" badge="$9/mo">
        <ul className="mt-2 text-[13px] text-muted-foreground">
          <li>Unlimited listings</li>
        </ul>
      </RadioGroupItem>
    </RadioGroupRoot>
  )
}

Props

• optionsdefault "[]"
  RadioOption[]

  The choices: { value, label, description?, icon?, badge?, disabled? }. badge is a trailing price or tag on the label's line. For layouts an array cannot express, compose RadioGroupRoot with RadioGroupItem children (see Parts).

• value
  string

  The chosen value when controlled. Pair it with onValueChange.

• onValueChange
  (value: string) => void

  Called with the new value when the person picks an option, by pointer, Space or the arrow keys. Not called while readOnly.

• labeldefault ""
  ReactNode

  The group's label, above the options. It names the radiogroup through aria-labelledby, and clicking it focuses the chosen option. Leave it empty and pass aria-label for a bare group.

• descriptiondefault ""
  ReactNode

  Helper text under the options, linked with aria-describedby. The error takes its place while it shows.

• errordefault ""
  ReactNode

  Replaces the description with an alert icon and the text, slides in and marks the group invalid: empty circles and card borders turn red.

• requireddefault false
  boolean

  The red mark after the label, aria-required on the group, and required on the hidden form inputs, so a native form will not submit without a choice.

• invaliddefault false
  boolean

  The invalid look and aria-invalid without a message, for forms that show errors elsewhere.

• disableddefault false
  boolean

  Dims every option and blocks it; a form will not submit its value. Disable one option through its own disabled.

• readOnlydefault false
  boolean

  The choice stays visible and focusable, but clicks and arrow keys do not change it (aria-readonly). No hover tint, no press dip.

• variantdefault "default"
  "default" | "card"

  default: compact rows with the circle beside the text. card: soft-filled tiles with an icon tile, a description and a trailing price, and one selection ring that slides between cards.

• sizedefault "md"
  "sm" | "md" | "lg"

  Circle 16 / 18 / 20px with a 6 / 7 / 8px dot, label 13 / 14 / 15px, card padding 12 / 16 / 20px.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The checked fill, the dot's contrast color and the card ring. neutral is black in light mode and white in dark mode; brand orange is opt-in.

• colordefault ""
  string

  Any CSS color. Replaces the tone; the dot turns black or white by lightness. Leave empty to use the tone.

• indicatordefault "dot"
  "dot" | "check"

  What appears in the filled circle: a dot that springs in, or a check mark that draws itself (nice on cards).

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Cards only: corners of 0 / 12 / 16 / 24px (full falls back to 24px). The ring follows it.

• orientationdefault "vertical"
  "vertical" | "horizontal"

  horizontal puts rows side by side and wraps them onto the next line instead of scrolling; cards share the row until they would get narrower than 10rem. Every arrow key works in both, like native radios.

• columnsdefault 1
  1 | 2 | 3 | 4

  Up to this many columns of rows or cards. The grid follows the space it has, not the viewport: it drops a column whenever cells would get narrower than 12rem (cards) or 11rem (rows), so a phone always gets one column and a narrow sidebar never squeezes the text.

• controlPositiondefault "auto"
  "auto" | "start" | "end"

  Where the circle sits: auto is before the text for rows and at the top end of cards. end suits settings lists; start suits cards that read like a checklist.

• showControldefault true
  boolean

  Cards only: false hides the circle and lets the ring and the tinted icon tile show the choice (plan pickers). The radio stays in the accessibility tree.

• defaultValuedefault ""
  string

  The option chosen on first render while uncontrolled. "" chooses nothing, and the first enabled option is then the tab stop. A value that matches no option also shows nothing chosen. The demo starts on curier while this is empty; try easybox or ridicare.

• loopdefault true
  boolean

  The arrow keys wrap from the last option to the first and back. The demo's key hint says which.

• namedefault ""
  string

  Form field name. Inside a <form> each option renders a hidden native radio with this name, so FormData and native validation work; a form reset returns to defaultValue. The demo prints what the form would submit.

• id
  string

  The group's id (the radiogroup element). Defaults to useId(); the label and messages derive their ids from it.

• fieldProps
  Partial<FieldProps>

  Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.

• classNames
  Partial<Record<"group" | "option" | "body" | "item" | "indicator" | "icon" | "content" | "label" | "description" | "badge" | "ring" | "field" | "fieldLabel" | "fieldDescription" | "error", string>>

  Extra classes for the parts. label and description style each option's text; fieldLabel and fieldDescription the group's own label and hint; group is the radiogroup element, option each row or card, body the inner row of a card (the part that stacks when the card is narrow), item the circle.

• className
  string

  Classes for the outermost element: the Field wrapper when there is a label, description or error, otherwise the radiogroup. Override the tone vars here, e.g. [--tone:#7C3AED].

• ref
  RefObject<HTMLDivElement | null> or (node) => void

  The radiogroup element. Every other prop (aria-label, dir, form, data-*) lands there too.

Parts

FAQ

Used in

More React input components