Radio Group

A set of checkable buttons where only one can be selected at a time. Built for React applications with Next.js integration and TypeScript support.

You know those round buttons where you can only pick one option? Like choosing a shipping method or selecting a plan? That's radio groups - they make sure users can only pick one thing from a set of choices.

Select your preference

Classic radio group for single-choice selection:

Loading component...

Built on Radix UI RadioGroup with proper keyboard navigation and ARIA support. This free open source React component handles all the focus management and accessibility while looking exactly how you want it.

npx shadcn@latest add radio-group

When to use radio buttons

Radio buttons aren't just checkboxes that hate each other. They're for when you need exactly one choice:

Mutually exclusive options - Only one can be true
Always visible choices - All options shown upfront
Small sets of options - Usually 2-7 choices max
Important decisions - Users need to see all options
Default selections - One option can be pre-selected
Keyboard navigation - Arrow keys move between options

Useful radio group patterns

Settings and preferences

Common pattern for app settings:

Loading component...

"use client"import * as React from "react"import { Label } from "@/components/ui/label"import {  RadioGroup,  RadioGroupItem,} from "@/components/ui/radio-group"import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"export default function RadioGroupSettings() {  const [theme, setTheme] = React.useState("system")  const [notifications, setNotifications] = React.useState("all")  return (    <div       className="flex justify-center self-start pt-6 w-full"       style={{         all: 'revert',        display: 'flex',        justifyContent: 'center',        alignSelf: 'flex-start',        paddingTop: '1.5rem',        width: '100%',        fontSize: '14px',        lineHeight: '1.5',        letterSpacing: 'normal'      }}    >      <div className="w-full max-w-md space-y-4">        <Card>          <CardHeader>            <CardTitle>Appearance</CardTitle>            <CardDescription>              Choose how shadcn looks to you            </CardDescription>          </CardHeader>          <CardContent>            <RadioGroup value={theme} onValueChange={setTheme}>              <div className="flex items-center gap-3">                <RadioGroupItem value="light" id="light" />                <Label htmlFor="light">Light</Label>              </div>              <div className="flex items-center gap-3">                <RadioGroupItem value="dark" id="dark" />                <Label htmlFor="dark">Dark</Label>              </div>              <div className="flex items-center gap-3">                <RadioGroupItem value="system" id="system" />                <Label htmlFor="system">System</Label>              </div>            </RadioGroup>          </CardContent>        </Card>        <Card>          <CardHeader>            <CardTitle>Notifications</CardTitle>            <CardDescription>              Choose what you want to be notified about            </CardDescription>          </CardHeader>          <CardContent>            <RadioGroup value={notifications} onValueChange={setNotifications}>              <div className="flex items-center gap-3">                <RadioGroupItem value="all" id="all" />                <Label htmlFor="all">All notifications</Label>              </div>              <div className="flex items-center gap-3">                <RadioGroupItem value="mentions" id="mentions" />                <Label htmlFor="mentions">Mentions only</Label>              </div>              <div className="flex items-center gap-3">                <RadioGroupItem value="none" id="none" />                <Label htmlFor="none">Nothing</Label>              </div>            </RadioGroup>          </CardContent>        </Card>      </div>    </div>  )}

Form with validation

Integrated with react-hook-form and validation:

Loading component...

"use client"import { zodResolver } from "@hookform/resolvers/zod"import { useForm } from "react-hook-form"import { toast } from "sonner"import { z } from "zod"import { Button } from "@/components/ui/button"import {  Form,  FormControl,  FormField,  FormItem,  FormLabel,  FormMessage,} from "@/components/ui/form"import {  RadioGroup,  RadioGroupItem,} from "@/components/ui/radio-group"const FormSchema = z.object({  type: z.enum(["all", "mentions", "none"], {    required_error: "You need to select a notification type.",  }),})export default function RadioGroupForm() {  const form = useForm<z.infer<typeof FormSchema>>({    resolver: zodResolver(FormSchema),  })  function onSubmit(data: z.infer<typeof FormSchema>) {    toast("You submitted the following values", {      description: (        <pre className="mt-2 w-[320px] rounded-md bg-neutral-950 p-4">          <code className="text-white">{JSON.stringify(data, null, 2)}</code>        </pre>      ),    })  }  return (    <div       className="flex justify-center self-start pt-6 w-full"       style={{         all: 'revert',        display: 'flex',        justifyContent: 'center',        alignSelf: 'flex-start',        paddingTop: '1.5rem',        width: '100%',        fontSize: '14px',        lineHeight: '1.5',        letterSpacing: 'normal'      }}    >      <Form {...form}>        <form onSubmit={form.handleSubmit(onSubmit)} className="w-2/3 space-y-6">          <FormField            control={form.control}            name="type"            render={({ field }) => (              <FormItem className="space-y-3">                <FormLabel>Notify me about...</FormLabel>                <FormControl>                  <RadioGroup                    onValueChange={field.onChange}                    defaultValue={field.value}                    className="flex flex-col"                  >                    <FormItem className="flex items-center gap-3">                      <FormControl>                        <RadioGroupItem value="all" />                      </FormControl>                      <FormLabel className="font-normal">                        All new messages                      </FormLabel>                    </FormItem>                    <FormItem className="flex items-center gap-3">                      <FormControl>                        <RadioGroupItem value="mentions" />                      </FormControl>                      <FormLabel className="font-normal">                        Direct messages and mentions                      </FormLabel>                    </FormItem>                    <FormItem className="flex items-center gap-3">                      <FormControl>                        <RadioGroupItem value="none" />                      </FormControl>                      <FormLabel className="font-normal">Nothing</FormLabel>                    </FormItem>                  </RadioGroup>                </FormControl>                <FormMessage />              </FormItem>            )}          />          <Button type="submit">Submit</Button>        </form>      </Form>    </div>  )}

import * as React from "react"import { Slot } from "@radix-ui/react-slot"import { cva, type VariantProps } from "class-variance-authority"import { cn } from "@/lib/utils"const buttonVariants = cva(  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",  {    variants: {      variant: {        default:          "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",        destructive:          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",        outline:          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",        secondary:          "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",        ghost:          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",        link: "text-primary underline-offset-4 hover:underline",      },      size: {        default: "h-9 px-4 py-2 has-[>svg]:px-3",        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",        icon: "size-9",      },    },    defaultVariants: {      variant: "default",      size: "default",    },  })function Button({  className,  variant,  size,  asChild = false,  ...props}: React.ComponentProps<"button"> &  VariantProps<typeof buttonVariants> & {    asChild?: boolean  }) {  const Comp = asChild ? Slot : "button"  return (    <Comp      data-slot="button"      className={cn(buttonVariants({ variant, size, className }))}      {...props}    />  )}export { Button, buttonVariants }

Cards layout

Sometimes radio buttons work better as cards:

Loading component...

"use client"import * as React from "react"import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"import { Label } from "@/components/ui/label"import { Card } from "@/components/ui/card"import { Zap, Rocket, Crown } from "lucide-react"import { cn } from "@/lib/utils"export default function RadioGroupCards() {  const [selected, setSelected] = React.useState("standard")  const plans = [    {      value: "free",      title: "Free",      description: "Great for trying things out",      price: "$0",      icon: Zap,      features: ["5 projects", "Basic support", "1 GB storage"]    },    {      value: "standard",      title: "Standard",      description: "Perfect for small teams",      price: "$15",      icon: Rocket,      features: ["Unlimited projects", "Priority support", "10 GB storage"]    },    {      value: "premium",      title: "Premium",      description: "For power users",      price: "$30",      icon: Crown,      features: ["Everything in Standard", "Advanced features", "100 GB storage"]    }  ]  return (    <div       className="flex justify-center self-start pt-6 w-full"       style={{         all: 'revert',        display: 'flex',        justifyContent: 'center',        alignSelf: 'flex-start',        paddingTop: '1.5rem',        width: '100%',        fontSize: '14px',        lineHeight: '1.5',        letterSpacing: 'normal'      }}    >      <div className="w-full max-w-3xl">        <div className="space-y-1.5 mb-4">          <h3 className="font-semibold leading-none">Choose your plan</h3>          <p className="text-sm text-muted-foreground">Select the plan that works best for you</p>        </div>        <RadioGroup value={selected} onValueChange={setSelected}>          <div className="grid gap-4 md:grid-cols-3">            {plans.map((plan) => {              const Icon = plan.icon              return (                <Label                  key={plan.value}                  htmlFor={plan.value}                  className="cursor-pointer"                >                  <Card className={cn(                    "relative overflow-hidden transition-all hover:shadow-md",                    selected === plan.value && "border-primary shadow-sm"                  )}>                    <div className="p-6 space-y-4">                      <div className="flex items-start justify-between">                        <Icon className="h-8 w-8 text-primary" />                        <RadioGroupItem                           value={plan.value}                           id={plan.value}                          className="mt-1"                        />                      </div>                      <div className="space-y-1">                        <h4 className="font-semibold">{plan.title}</h4>                        <p className="text-sm text-muted-foreground">                          {plan.description}                        </p>                      </div>                      <div className="text-2xl font-bold">                        {plan.price}                        <span className="text-sm font-normal text-muted-foreground">/month</span>                      </div>                      <ul className="space-y-1 text-sm">                        {plan.features.map((feature, i) => (                          <li key={i} className="flex items-center gap-2">                            <div className="h-1.5 w-1.5 rounded-full bg-primary" />                            {feature}                          </li>                        ))}                      </ul>                    </div>                  </Card>                </Label>              )            })}          </div>        </RadioGroup>      </div>    </div>  )}

These patterns show up everywhere because they solve real problems. Settings that need one choice, form fields that need validation, survey questions that need a single answer.

Perfect for forms and settings

Works great anywhere users need to make a single choice from a visible set - checkout flows, settings panels, surveys, configuration wizards. The kind of decisions where seeing all options matters.

Drops right into Next.js projects. Full TypeScript support. Styled with Tailwind CSS to match the shadcn design system.

Built with Radix UI

Under the hood it's Radix UI RadioGroup, which handles the tricky stuff:

Roving tabindex - One tab stop, then arrow keys
Automatic IDs - Labels and inputs connected properly
Group management - Only one selected at a time
Orientation support - Vertical or horizontal layouts
Loop navigation - Arrow keys wrap around
Form integration - Works with native form submission

API Reference

RadioGroup

The root container that manages radio state.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes
`defaultValue`	`string`	-	Default selected value for uncontrolled
`value`	`string`	-	Controlled selected value
`onValueChange`	`(value: string) => void`	-	Called when selection changes
`disabled`	`boolean`	`false`	Disable all radio items
`name`	`string`	-	Name for form submission
`required`	`boolean`	`false`	Whether selection is required
`orientation`	`"horizontal" \| "vertical"`	`"vertical"`	Layout direction
`loop`	`boolean`	`true`	Whether keyboard nav loops

Data attributes:

[data-disabled]: Present when disabled

RadioGroupItem

Individual radio button in the group.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes
`value`	`string`	required	Value for this option
`id`	`string`	-	ID for label association
`disabled`	`boolean`	`false`	Disable this specific item

Data attributes:

[data-state]: "checked" | "unchecked"
[data-disabled]: Present when disabled

Key	Action
`Tab`	Focus the radio group
`Space`	Select focused item
`Arrow Down`	Move focus to next item
`Arrow Right`	Move focus to next item
`Arrow Up`	Move focus to previous item
`Arrow Left`	Move focus to previous item
`Home`	Focus first item
`End`	Focus last item

Form Integration

Works with react-hook-form and other form libraries:

<FormField
  control={form.control}
  name="option"
  render={({ field }) => (
    <RadioGroup
      onValueChange={field.onChange}
      defaultValue={field.value}
    >
      <RadioGroupItem value="option1" />
      <RadioGroupItem value="option2" />
    </RadioGroup>
  )}
/>

Common Patterns

Pattern	Use Case	Implementation
Inline labels	Compact forms	Label next to radio
Stacked labels	Mobile-friendly	Label below radio
Card selection	Visual options	Radio inside card component
Icon options	Visual choices	Icon + label + radio
Description text	Complex options	Title + description per item

Make radio groups that work

Few things to keep in mind:

Always have a default - Don't make users think about the obvious choice
Keep groups small - More than 7 options? Maybe use a select instead
Labels that click - Make the whole label clickable, not just the circle
Group related options - Visual spacing helps scanning
Clear option names - "Yes/No" beats "Enable/Disable"
Consider the layout - Vertical for most things, horizontal for short lists
Show the selection - Make it super obvious what's selected
Test keyboard navigation - Should feel natural with arrow keys

Select your preference

When to use radio buttons

Useful radio group patterns

Settings and preferences

Form with validation

Cards layout

Perfect for forms and settings

Built with Radix UI

API Reference

RadioGroup

RadioGroupItem

Keyboard Navigation

Form Integration

Common Patterns

Make radio groups that work

On this page

Radio Group

Reactlabel

Reactradio-group

Reactlabel

Reactradio-group

Reactcard

Reactbutton

Reactform

Reactradio-group

Reactradio-group

Reactlabel

Reactcard

On this page