Radio Group

Notifications

All new messagesDirect messages and mentionsNothing

import { Radio, RadioGroup } from "@/components/ui/radio-group";

export default function RadioGroupDemo() {
  return (
    <RadioGroup label="Notifications" defaultValue="mentions">
      <Radio value="all">All new messages</Radio>
      <Radio value="mentions">Direct messages and mentions</Radio>
      <Radio value="none">Nothing</Radio>
    </RadioGroup>
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/radio-group

The CLI installs dependencies and any other components this one uses.

Usage

tsx

import { Radio, RadioCard, RadioGroup } from "@/components/ui/radio-group";

tsx

<RadioGroup label="Size" defaultValue="m">
  <Radio value="s">Small</Radio>
  <Radio value="m">Medium</Radio>
  <Radio value="l">Large</Radio>
</RadioGroup>

The group owns the value: a single string matching one radio's value. Radio and RadioCard can be mixed freely inside the same group.

When to use

Radio Group — one choice from about 2–6 options that users should compare side by side.
Select — one choice from a longer list, or when space is tight.
Checkbox — any number of choices, or a single yes/no that's submitted with a form.
Switch — a single on/off setting that applies immediately.
Toggle Button Group — a compact, button-styled choice such as alignment or view mode.

Anatomy

tsx

<RadioGroup>                {/* label, description, error message */}
  <Radio value="…">Label</Radio>
  <RadioCard value="…" icon={…} title="…" description="…" />
</RadioGroup>

Part	Renders	Notes
`RadioGroup`	`<div role="radiogroup">`	Wraps the label, description, radios and error message. `orientation` controls the layout.
`Radio`	`<label>` + hidden `<input type="radio">`	A dot and a label. With `description`, the label becomes a bold title with secondary text under it.
`RadioCard`	`<label>` + hidden `<input type="radio">`	A bordered card with an optional `icon`, a `title`, a `description` and a trailing dot.
Label / Description	`<span>`	Rendered from the group's `label` and `description` props.
`FieldError`	`<div>`	Rendered by the group when validation fails; shows `errorMessage` or the browser message.

Examples

Horizontal

orientation="horizontal" lays radios out in a wrapping row and sets aria-orientation. Use it for 2–4 short labels.

Density

CompactComfortableSpacious

import { Radio, RadioGroup } from "@/components/ui/radio-group";

export default function RadioGroupHorizontal() {
  return (
    <RadioGroup
      label="Density"
      orientation="horizontal"
      defaultValue="comfortable"
    >
      <Radio value="compact">Compact</Radio>
      <Radio value="comfortable">Comfortable</Radio>
      <Radio value="spacious">Spacious</Radio>
    </RadioGroup>
  );
}

With descriptions

description on a Radio adds secondary text under the label. Use it when the labels alone don't explain the difference between options.

Visibility

PublicAnyone on the internet can see this project.InternalEveryone in your organization can see it.PrivateOnly people you invite can see it.

import { Radio, RadioGroup } from "@/components/ui/radio-group";

export default function RadioGroupDescription() {
  return (
    <RadioGroup label="Visibility" defaultValue="private" className="max-w-xs">
      <Radio
        value="public"
        description="Anyone on the internet can see this project."
      >
        Public
      </Radio>
      <Radio
        value="internal"
        description="Everyone in your organization can see it."
      >
        Internal
      </Radio>
      <Radio value="private" description="Only people you invite can see it.">
        Private
      </Radio>
    </RadioGroup>
  );
}

isDisabled on a Radio makes just that option unavailable while keeping it visible; explain why in the group's description. isDisabled on the group disables every option. isReadOnly shows the value but ignores changes, and keeps the group focusable.

import { Radio, RadioGroup } from "@/components/ui/radio-group";

export default function RadioGroupDisabled() {
  return (
    <div className="flex flex-col gap-8">
      <RadioGroup
        label="Region"
        description="Tokyo is at capacity. Try again next week."
        defaultValue="fra"
      >
        <Radio value="iad">Washington, D.C. (iad1)</Radio>
        <Radio value="fra">Frankfurt (fra1)</Radio>
        <Radio value="hnd" isDisabled>
          Tokyo (hnd1)
        </Radio>
      </RadioGroup>
      <RadioGroup label="Billing cycle" isReadOnly defaultValue="yearly">
        <Radio value="monthly">Monthly</Radio>
        <Radio value="yearly">Yearly</Radio>
      </RadioGroup>
      <RadioGroup label="Data residency" isDisabled defaultValue="eu">
        <Radio value="us">United States</Radio>
        <Radio value="eu">European Union</Radio>
      </RadioGroup>
    </div>
  );
}

Controlled

Use value and onChange to own the selection. onChange receives the selected radio's value.

Digest frequency

DailyWeeklyMonthlyNever

You'll get a digest weekly.

import { useState } from "react";
import { Radio, RadioGroup } from "@/components/ui/radio-group";

export default function RadioGroupControlled() {
  const [value, setValue] = useState("weekly");
  return (
    <div className="flex flex-col gap-4">
      <RadioGroup label="Digest frequency" value={value} onChange={setValue}>
        <Radio value="daily">Daily</Radio>
        <Radio value="weekly">Weekly</Radio>
        <Radio value="monthly">Monthly</Radio>
        <Radio value="never">Never</Radio>
      </RadioGroup>
      <p className="text-muted-foreground text-sm">
        You'll get a digest{" "}
        <span className="font-medium text-foreground">
          {value === "never" ? "never" : value}
        </span>
        .
      </p>
    </div>
  );
}

Cards

RadioCard is a larger target with a leading icon, a title and a description. The whole card is the label, and the selected card gets a brand-colored border.

Plan

PersonalFor individuals. Up to 3 projects.Team$12 per seat. Unlimited projects.EnterpriseSSO, audit logs and dedicated support.

import { BuildingIcon, RocketIcon, UserIcon } from "lucide-react";
import { RadioCard, RadioGroup } from "@/components/ui/radio-group";

export default function RadioGroupCards() {
  return (
    <RadioGroup label="Plan" defaultValue="team" className="w-full max-w-sm">
      <RadioCard
        value="personal"
        icon={<UserIcon />}
        title="Personal"
        description="For individuals. Up to 3 projects."
      />
      <RadioCard
        value="team"
        icon={<RocketIcon />}
        title="Team"
        description="$12 per seat. Unlimited projects."
      />
      <RadioCard
        value="enterprise"
        icon={<BuildingIcon />}
        title="Enterprise"
        description="SSO, audit logs and dedicated support."
      />
    </RadioGroup>
  );
}

Card grid

In a horizontal group, give each card flex-1 and a min-w-* so they share the row evenly and wrap on narrow screens.

Payment method

CardVisa, Mastercard, AmexBank transfer2–3 business daysWalletApple Pay, Google Pay

import { CreditCardIcon, LandmarkIcon, WalletIcon } from "lucide-react";
import { RadioCard, RadioGroup } from "@/components/ui/radio-group";

export default function RadioGroupCardGrid() {
  return (
    <RadioGroup
      label="Payment method"
      orientation="horizontal"
      defaultValue="card"
      className="w-full max-w-xl"
    >
      <RadioCard
        value="card"
        icon={<CreditCardIcon />}
        title="Card"
        description="Visa, Mastercard, Amex"
        className="min-w-40 flex-1"
      />
      <RadioCard
        value="bank"
        icon={<LandmarkIcon />}
        title="Bank transfer"
        description="2–3 business days"
        className="min-w-40 flex-1"
      />
      <RadioCard
        value="wallet"
        icon={<WalletIcon />}
        title="Wallet"
        description="Apple Pay, Google Pay"
        className="min-w-40 flex-1"
      />
    </RadioGroup>
  );
}

With a follow-up input

Control the group to reveal a related field when a specific option is picked, like "Something else". Place the input after the group, not inside a radio's label.

Why are you cancelling?

It's too expensiveIt's missing features I needI'm switching to another productSomething else

import { useState } from "react";
import { Radio, RadioGroup } from "@/components/ui/radio-group";
import { TextField } from "@/components/ui/text-field";

export default function RadioGroupWithInput() {
  const [reason, setReason] = useState("price");
  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <RadioGroup
        label="Why are you cancelling?"
        value={reason}
        onChange={setReason}
      >
        <Radio value="price">It's too expensive</Radio>
        <Radio value="features">It's missing features I need</Radio>
        <Radio value="switch">I'm switching to another product</Radio>
        <Radio value="other">Something else</Radio>
      </RadioGroup>
      {reason === "other" && (
        <TextField
          aria-label="Tell us more"
          placeholder="Tell us more…"
          autoFocus
          className="pl-6"
        />
      )}
    </div>
  );
}

Required and validation

isRequired blocks form submission until an option is selected and adds a * to the label. With native validation, the errorMessage appears after the first submit attempt.

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { Radio, RadioGroup } from "@/components/ui/radio-group";

export default function RadioGroupValidation() {
  return (
    <Form
      className="flex w-full max-w-xs flex-col gap-5"
      onSubmit={(e) => e.preventDefault()}
    >
      <RadioGroup
        label="Team size"
        isRequired
        errorMessage="Select your team size to continue."
      >
        <Radio value="1">Just me</Radio>
        <Radio value="2-10">2–10 people</Radio>
        <Radio value="11-50">11–50 people</Radio>
        <Radio value="51+">More than 50</Radio>
      </RadioGroup>
      <Button type="submit" className="self-start">
        Continue
      </Button>
    </Form>
  );
}

Custom validation

validate receives the selected value and returns an error string, or null when valid. With validationBehavior="aria" the message updates live as the selection changes.

Shipping to a P.O. box

Standard5–7 business days · FreeExpress2–3 business days · $9.00OvernightNext business day · $24.00

import { Radio, RadioGroup } from "@/components/ui/radio-group";

export default function RadioGroupCustomValidation() {
  return (
    <RadioGroup
      label="Shipping to a P.O. box"
      defaultValue="standard"
      validationBehavior="aria"
      validate={(value) =>
        value === "overnight"
          ? "Overnight delivery isn't available for P.O. boxes."
          : null
      }
    >
      <Radio value="standard" description="5–7 business days · Free">
        Standard
      </Radio>
      <Radio value="express" description="2–3 business days · $9.00">
        Express
      </Radio>
      <Radio value="overnight" description="Next business day · $24.00">
        Overnight
      </Radio>
    </RadioGroup>
  );
}

Form submission

Give the group a name and the selected radio's value is submitted under it, exactly like native radio buttons.

import { useState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { Radio, RadioGroup } from "@/components/ui/radio-group";

export default function RadioGroupForm() {
  const [result, setResult] = useState<string | null>(null);
  return (
    <Form
      className="flex w-full max-w-xs flex-col gap-5"
      onSubmit={(e) => {
        e.preventDefault();
        setResult(
          JSON.stringify(Object.fromEntries(new FormData(e.currentTarget))),
        );
      }}
    >
      <RadioGroup label="Size" name="size" defaultValue="m" isRequired>
        <Radio value="s">Small</Radio>
        <Radio value="m">Medium</Radio>
        <Radio value="l">Large</Radio>
      </RadioGroup>
      <RadioGroup
        label="Milk"
        name="milk"
        orientation="horizontal"
        defaultValue="oat"
      >
        <Radio value="whole">Whole</Radio>
        <Radio value="oat">Oat</Radio>
        <Radio value="none">None</Radio>
      </RadioGroup>
      <Button type="submit" className="self-start">
        Add to order
      </Button>
      {result && (
        <code className="rounded-md bg-muted px-2 py-1 text-xs">{result}</code>
      )}
    </Form>
  );
}

Recipes

Plan picker

Cards whose title is a composed node with a Badge and a price. A Switch toggles yearly billing.

Bill yearly (save 20%)

Plan

HobbyFree1 project, community supportProPopular$16/moUnlimited projects, preview deploysTeam$36/moSSO, roles and audit log

import { BuildingIcon, RocketIcon, UserIcon } from "lucide-react";
import { useState } from "react";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { RadioCard, RadioGroup } from "@/components/ui/radio-group";
import { Switch } from "@/components/ui/switch";

const plans = [
  {
    id: "hobby",
    name: "Hobby",
    icon: <UserIcon />,
    monthly: 0,
    blurb: "1 project, community support",
  },
  {
    id: "pro",
    name: "Pro",
    icon: <RocketIcon />,
    monthly: 20,
    blurb: "Unlimited projects, preview deploys",
    popular: true,
  },
  {
    id: "team",
    name: "Team",
    icon: <BuildingIcon />,
    monthly: 45,
    blurb: "SSO, roles and audit log",
  },
];

export default function RadioGroupRecipePlanPicker() {
  const [plan, setPlan] = useState("pro");
  const [yearly, setYearly] = useState(true);
  const price = (monthly: number) =>
    monthly === 0
      ? "Free"
      : `$${yearly ? Math.round(monthly * 0.8) : monthly}/mo`;

  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <Switch isSelected={yearly} onChange={setYearly} size="sm">
        Bill yearly (save 20%)
      </Switch>
      <RadioGroup
        label="Plan"
        value={plan}
        onChange={setPlan}
        className="w-full"
      >
        {plans.map((p) => (
          <RadioCard
            key={p.id}
            value={p.id}
            icon={p.icon}
            title={
              <span className="flex items-center gap-2">
                {p.name}
                {p.popular && (
                  <Badge color="brand" size="sm">
                    Popular
                  </Badge>
                )}
                <span className="ml-auto text-muted-foreground tabular-nums">
                  {price(p.monthly)}
                </span>
              </span>
            }
            description={p.blurb}
          />
        ))}
      </RadioGroup>
      <Button className="w-full">
        Continue with {plans.find((p) => p.id === plan)?.name}
      </Button>
    </div>
  );
}

Shipping method

A checkout step where the selected card updates the order total.

Shipping method

StandardFreeArrives Mon, Jun 16Express$9.00Arrives Thu, Jun 12Overnight$24.00Arrives tomorrow

Subtotal: $128.00
Shipping: Free
Total: $128.00

import { useState } from "react";
import { RadioCard, RadioGroup } from "@/components/ui/radio-group";

const methods = [
  { id: "standard", name: "Standard", eta: "Arrives Mon, Jun 16", price: 0 },
  { id: "express", name: "Express", eta: "Arrives Thu, Jun 12", price: 9 },
  { id: "overnight", name: "Overnight", eta: "Arrives tomorrow", price: 24 },
];

const subtotal = 128;
const usd = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
});

export default function RadioGroupRecipeShipping() {
  const [method, setMethod] = useState("standard");
  const shipping = methods.find((m) => m.id === method)?.price ?? 0;

  return (
    <div className="flex w-full max-w-sm flex-col gap-5 rounded-xl border bg-card p-5">
      <RadioGroup
        label="Shipping method"
        value={method}
        onChange={setMethod}
        name="shipping"
      >
        {methods.map((m) => (
          <RadioCard
            key={m.id}
            value={m.id}
            title={
              <span className="flex justify-between gap-2">
                {m.name}
                <span className="tabular-nums">
                  {m.price === 0 ? "Free" : usd.format(m.price)}
                </span>
              </span>
            }
            description={m.eta}
          />
        ))}
      </RadioGroup>
      <dl className="grid grid-cols-[1fr_auto] gap-y-1.5 border-t pt-4 text-sm">
        <dt className="text-muted-foreground">Subtotal</dt>
        <dd className="tabular-nums">{usd.format(subtotal)}</dd>
        <dt className="text-muted-foreground">Shipping</dt>
        <dd className="tabular-nums">
          {shipping === 0 ? "Free" : usd.format(shipping)}
        </dd>
        <dt className="font-medium">Total</dt>
        <dd className="font-medium tabular-nums">
          {usd.format(subtotal + shipping)}
        </dd>
      </dl>
    </div>
  );
}

Privacy settings

Two controlled groups in a settings card, with Save and Discard enabled only when the draft differs from the saved value.

Privacy

Control who can find you and contact you.

Who can see your profile

PublicAnyone, including search engines.Workspace membersOnly people signed in to this workspace.PrivateOnly you and admins.

Who can message you

EveryoneMy teamNobody

import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Radio, RadioGroup } from "@/components/ui/radio-group";

const initial = { profile: "members", messages: "everyone" };

export default function RadioGroupRecipePrivacy() {
  const [saved, setSaved] = useState(initial);
  const [draft, setDraft] = useState(initial);
  const isDirty =
    draft.profile !== saved.profile || draft.messages !== saved.messages;

  return (
    <div className="w-full max-w-md divide-y rounded-xl border bg-card">
      <div className="p-5">
        <h3 className="font-semibold">Privacy</h3>
        <p className="text-muted-foreground text-sm">
          Control who can find you and contact you.
        </p>
      </div>
      <div className="grid gap-6 p-5">
        <RadioGroup
          label="Who can see your profile"
          value={draft.profile}
          onChange={(profile) => setDraft((d) => ({ ...d, profile }))}
        >
          <Radio value="public" description="Anyone, including search engines.">
            Public
          </Radio>
          <Radio
            value="members"
            description="Only people signed in to this workspace."
          >
            Workspace members
          </Radio>
          <Radio value="private" description="Only you and admins.">
            Private
          </Radio>
        </RadioGroup>
        <RadioGroup
          label="Who can message you"
          orientation="horizontal"
          value={draft.messages}
          onChange={(messages) => setDraft((d) => ({ ...d, messages }))}
        >
          <Radio value="everyone">Everyone</Radio>
          <Radio value="team">My team</Radio>
          <Radio value="nobody">Nobody</Radio>
        </RadioGroup>
      </div>
      <div className="flex justify-end gap-2 bg-muted/30 px-5 py-3">
        <Button
          variant="ghost"
          isDisabled={!isDirty}
          onPress={() => setDraft(saved)}
        >
          Discard
        </Button>
        <Button isDisabled={!isDirty} onPress={() => setSaved(draft)}>
          Save changes
        </Button>
      </div>
    </div>
  );
}

Accessibility

Every radio is a native <input type="radio"> visually hidden inside a <label>, so the whole label (or card) is clickable and native forms work.
The group has role="radiogroup", is labelled by label, and links its description and error message with aria-describedby.
The group is a single tab stop: focus lands on the selected radio (or the first one when nothing is selected), and arrow keys move the selection.
A group without a visible label needs aria-label or aria-labelledby.
description on a Radio and title / description on a RadioCard are inside the <label>, so they're read as part of the option's name. Keep them concise.
The focus ring only appears for keyboard focus (data-focus-visible).

Keyboard

Key	Action
`Tab`	Moves focus into the group, to the selected radio
`↓` / `→`	Selects the next radio, wrapping to the first
`↑` / `←`	Selects the previous radio, wrapping to the last
`Space`	Selects the focused radio, if it isn't already

Styling

Data attributes

On Radio and RadioCard (target inner parts with group-data-*/radio:):

Attribute	Present when
`data-selected`	The radio is the group's value
`data-hovered`	Hovered with a mouse or pen
`data-pressed`	Being pressed
`data-focused` / `data-focus-visible`	Focused / focused with the keyboard
`data-disabled`	Disabled, directly or through the group
`data-readonly`	The group is read-only
`data-invalid`	The group is invalid
`data-required`	The group is required

On RadioGroup (children can use group-data-*/field:):

Attribute	Present when
`data-orientation`	`"horizontal"` or `"vertical"`
`data-disabled` / `data-readonly`	Disabled / read-only
`data-required` / `data-invalid`	Required / validation failed

Slots

`data-slot`	Element
`radio-group`	Group root
`radio`	Each `Radio`'s `<label>` root
`radio-card`	Each `RadioCard`'s `<label>` root
`label`, `description`, `field-error`	Group label, description and error message

Color

The dot, hover border and selected card use the --brand theme variable. Override it on a group or a single radio:

tsx

<RadioGroup label="Status" className="[--brand:var(--color-emerald-600)]">
  …
</RadioGroup>

Render props

Radio's className and children accept a function of its state; RadioCard's className does too:

tsx

<Radio value="pro" className={({ isSelected }) => (isSelected ? "font-medium" : "")}>
  Pro
</Radio>

API Reference

RadioGroup

Prop

Type

Also accepts every prop of React Aria's RadioGroup.

Radio

Prop

Type

RadioCard

Prop

Type

RadioCard accepts the same React Aria props as Radio, except children: its content comes from title, description and icon. See React Aria's Radio props.

Checkbox — for multiple choices.
Select — for a single choice from a longer list.
Toggle Button Group — single selection as buttons.
Switch — for an on/off setting.