Get Started
Components
- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
AI Elements
Libraries
Utilities
"use client";
import * as React from "react";
import { cn } from "@/lib/utils";
interface RadioGroupContextValue {
disabled: boolean;
name: string;
registerItem: (value: string) => () => void;
setValue: (value: string) => void;
value: string;
}
const RadioGroupContext = React.createContext<RadioGroupContextValue | null>(
null
);
function useRadioGroupContext(): RadioGroupContextValue {
const ctx = React.useContext(RadioGroupContext);
if (!ctx) {
throw new Error("RadioGroupItem must be used within <RadioGroup>.");
}
return ctx;
}
type RadioGroupProps = Omit<
React.ComponentPropsWithoutRef<"div">,
"defaultValue"
> & {
value?: string;
defaultValue?: string;
onValueChange?: (value: string) => void;
disabled?: boolean;
name?: string;
required?: boolean;
orientation?: "horizontal" | "vertical";
};
function RadioGroup({
className,
defaultValue = "",
disabled = false,
name: nameProp,
onKeyDown,
onValueChange,
orientation = "vertical",
required = false,
value: valueProp,
...props
}: RadioGroupProps) {
const isControlled = valueProp !== undefined;
const [uncontrolled, setUncontrolled] = React.useState(defaultValue);
const value = isControlled ? valueProp : uncontrolled;
const groupName = React.useId().replace(/:/gu, "");
const name = nameProp ?? groupName;
const itemsRef = React.useRef<string[]>([]);
const registerItem = React.useCallback((next: string) => {
if (!itemsRef.current.includes(next)) {
itemsRef.current = [...itemsRef.current, next];
}
return () => {
itemsRef.current = itemsRef.current.filter((x) => x !== next);
};
}, []);
const setValue = React.useCallback(
(next: string) => {
if (!isControlled) {
setUncontrolled(next);
}
onValueChange?.(next);
},
[isControlled, onValueChange]
);
const ctx = React.useMemo<RadioGroupContextValue>(
() => ({ disabled, name, registerItem, setValue, value }),
[disabled, name, registerItem, setValue, value]
);
const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
onKeyDown?.(event);
if (event.defaultPrevented) {
return;
}
const root = event.currentTarget;
const items = Array.from(
root.querySelectorAll<HTMLElement>(
"[data-slot=radio-group-item]:not([disabled])"
)
);
if (items.length === 0) {
return;
}
const currentIdx = items.indexOf(document.activeElement as HTMLElement);
if (currentIdx < 0) {
return;
}
const isVertical = orientation === "vertical";
const prevKey = isVertical ? "ArrowUp" : "ArrowLeft";
const nextKey = isVertical ? "ArrowDown" : "ArrowRight";
let nextIdx = -1;
if (event.key === nextKey) {
nextIdx = (currentIdx + 1) % items.length;
} else if (event.key === prevKey) {
nextIdx = (currentIdx - 1 + items.length) % items.length;
} else if (event.key === "Home") {
nextIdx = 0;
} else if (event.key === "End") {
nextIdx = items.length - 1;
}
if (nextIdx < 0) {
return;
}
event.preventDefault();
items[nextIdx].focus();
const nextValue = items[nextIdx].getAttribute("data-value");
if (nextValue) {
setValue(nextValue);
}
};
return (
<RadioGroupContext.Provider value={ctx}>
<div
{...props}
aria-disabled={disabled || undefined}
aria-orientation={orientation}
aria-required={required || undefined}
className={cn("grid w-full gap-2", className)}
data-disabled={disabled || undefined}
data-orientation={orientation}
data-slot="radio-group"
data-value={value}
onKeyDown={handleKeyDown}
role="radiogroup"
>
{props.children}
<input name={name} type="hidden" value={value} />
</div>
</RadioGroupContext.Provider>
);
}
type RadioGroupItemProps = Omit<
React.ComponentPropsWithoutRef<"button">,
"onChange" | "role" | "aria-checked" | "type" | "ref" | "value"
> & {
value: string;
ref?: React.Ref<HTMLButtonElement>;
};
function RadioGroupItem({
className,
disabled: disabledProp,
onClick,
ref,
value,
...props
}: RadioGroupItemProps) {
const ctx = useRadioGroupContext();
const isChecked = ctx.value === value;
const isDisabled = ctx.disabled || disabledProp === true;
const registerItem = ctx.registerItem;
React.useEffect(() => registerItem(value), [registerItem, value]);
const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
onClick?.(event);
if (event.defaultPrevented || isDisabled) {
return;
}
ctx.setValue(value);
};
return (
<button
{...props}
aria-checked={isChecked}
className={cn(
"group/radio-group-item peer border-input group-has-[:focus-visible]/field-label:not-data-checked:border-input focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground group-has-[:focus-visible]/field-label:data-checked:border-primary dark:data-checked:bg-primary relative flex aspect-square size-4 shrink-0 rounded-full border outline-none group-has-[:focus-visible]/field-label:ring-0 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:ring-3 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:ring-3",
className
)}
data-checked={isChecked ? "" : undefined}
data-slot="radio-group-item"
data-state={isChecked ? "checked" : "unchecked"}
data-value={value}
disabled={isDisabled}
onClick={handleClick}
ref={ref}
role="radio"
tabIndex={isChecked ? 0 : -1}
type="button"
>
{isChecked ? (
<span
aria-hidden="true"
className="flex size-4 items-center justify-center"
data-slot="radio-group-indicator"
>
<span className="bg-primary-foreground absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2 rounded-full" />
</span>
) : null}
</button>
);
}
export { RadioGroup, RadioGroupItem };Radio Group is a set of mutually exclusive options. Only one item can be selected at a time, and the group manages focus with arrow keys.
Installation
$ bunx --bun frakment add radio-group$ npx frakment add radio-group$ pnpm dlx frakment add radio-group$ yarn dlx frakment add radio-group
Copy and paste the following code into your project.
"use client";
import * as React from "react";
import { cn } from "@/lib/utils";
interface RadioGroupContextValue {
disabled: boolean;
name: string;
registerItem: (value: string) => () => void;
setValue: (value: string) => void;
value: string;
}
const RadioGroupContext = React.createContext<RadioGroupContextValue | null>(
null
);
function useRadioGroupContext(): RadioGroupContextValue {
const ctx = React.useContext(RadioGroupContext);
if (!ctx) {
throw new Error("RadioGroupItem must be used within <RadioGroup>.");
}
return ctx;
}
type RadioGroupProps = Omit<
React.ComponentPropsWithoutRef<"div">,
"defaultValue"
> & {
value?: string;
defaultValue?: string;
onValueChange?: (value: string) => void;
disabled?: boolean;
name?: string;
required?: boolean;
orientation?: "horizontal" | "vertical";
};
function RadioGroup({
className,
defaultValue = "",
disabled = false,
name: nameProp,
onKeyDown,
onValueChange,
orientation = "vertical",
required = false,
value: valueProp,
...props
}: RadioGroupProps) {
const isControlled = valueProp !== undefined;
const [uncontrolled, setUncontrolled] = React.useState(defaultValue);
const value = isControlled ? valueProp : uncontrolled;
const groupName = React.useId().replace(/:/gu, "");
const name = nameProp ?? groupName;
const itemsRef = React.useRef<string[]>([]);
const registerItem = React.useCallback((next: string) => {
if (!itemsRef.current.includes(next)) {
itemsRef.current = [...itemsRef.current, next];
}
return () => {
itemsRef.current = itemsRef.current.filter((x) => x !== next);
};
}, []);
const setValue = React.useCallback(
(next: string) => {
if (!isControlled) {
setUncontrolled(next);
}
onValueChange?.(next);
},
[isControlled, onValueChange]
);
const ctx = React.useMemo<RadioGroupContextValue>(
() => ({ disabled, name, registerItem, setValue, value }),
[disabled, name, registerItem, setValue, value]
);
const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
onKeyDown?.(event);
if (event.defaultPrevented) {
return;
}
const root = event.currentTarget;
const items = Array.from(
root.querySelectorAll<HTMLElement>(
"[data-slot=radio-group-item]:not([disabled])"
)
);
if (items.length === 0) {
return;
}
const currentIdx = items.indexOf(document.activeElement as HTMLElement);
if (currentIdx < 0) {
return;
}
const isVertical = orientation === "vertical";
const prevKey = isVertical ? "ArrowUp" : "ArrowLeft";
const nextKey = isVertical ? "ArrowDown" : "ArrowRight";
let nextIdx = -1;
if (event.key === nextKey) {
nextIdx = (currentIdx + 1) % items.length;
} else if (event.key === prevKey) {
nextIdx = (currentIdx - 1 + items.length) % items.length;
} else if (event.key === "Home") {
nextIdx = 0;
} else if (event.key === "End") {
nextIdx = items.length - 1;
}
if (nextIdx < 0) {
return;
}
event.preventDefault();
items[nextIdx].focus();
const nextValue = items[nextIdx].getAttribute("data-value");
if (nextValue) {
setValue(nextValue);
}
};
return (
<RadioGroupContext.Provider value={ctx}>
<div
{...props}
aria-disabled={disabled || undefined}
aria-orientation={orientation}
aria-required={required || undefined}
className={cn("grid w-full gap-2", className)}
data-disabled={disabled || undefined}
data-orientation={orientation}
data-slot="radio-group"
data-value={value}
onKeyDown={handleKeyDown}
role="radiogroup"
>
{props.children}
<input name={name} type="hidden" value={value} />
</div>
</RadioGroupContext.Provider>
);
}
type RadioGroupItemProps = Omit<
React.ComponentPropsWithoutRef<"button">,
"onChange" | "role" | "aria-checked" | "type" | "ref" | "value"
> & {
value: string;
ref?: React.Ref<HTMLButtonElement>;
};
function RadioGroupItem({
className,
disabled: disabledProp,
onClick,
ref,
value,
...props
}: RadioGroupItemProps) {
const ctx = useRadioGroupContext();
const isChecked = ctx.value === value;
const isDisabled = ctx.disabled || disabledProp === true;
const registerItem = ctx.registerItem;
React.useEffect(() => registerItem(value), [registerItem, value]);
const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
onClick?.(event);
if (event.defaultPrevented || isDisabled) {
return;
}
ctx.setValue(value);
};
return (
<button
{...props}
aria-checked={isChecked}
className={cn(
"group/radio-group-item peer border-input group-has-[:focus-visible]/field-label:not-data-checked:border-input focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground group-has-[:focus-visible]/field-label:data-checked:border-primary dark:data-checked:bg-primary relative flex aspect-square size-4 shrink-0 rounded-full border outline-none group-has-[:focus-visible]/field-label:ring-0 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:ring-3 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:ring-3",
className
)}
data-checked={isChecked ? "" : undefined}
data-slot="radio-group-item"
data-state={isChecked ? "checked" : "unchecked"}
data-value={value}
disabled={isDisabled}
onClick={handleClick}
ref={ref}
role="radio"
tabIndex={isChecked ? 0 : -1}
type="button"
>
{isChecked ? (
<span
aria-hidden="true"
className="flex size-4 items-center justify-center"
data-slot="radio-group-indicator"
>
<span className="bg-primary-foreground absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2 rounded-full" />
</span>
) : null}
</button>
);
}
export { RadioGroup, RadioGroupItem };Update the import paths to match your project setup.
Usage
import { Label } from "@/components/ui/label";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
<DocsBaseSwitcher base="web" component="radio-group" className="mb-6" /><RadioGroup defaultValue="comfortable">
<div className="flex items-center gap-3">
<RadioGroupItem value="default" id="r1" />
<Label htmlFor="r1">Default</Label>
</div>
<div className="flex items-center gap-3">
<RadioGroupItem value="comfortable" id="r2" />
<Label htmlFor="r2">Comfortable</Label>
</div>
</RadioGroup>Composition
RadioGroup
└── RadioGroupItemExamples
With description
Compose Field, FieldContent, and FieldDescription for helper text under each option.
Standard spacing for most use cases.
More space between elements.
Minimal spacing for dense layouts.
import {
Field,
FieldContent,
FieldDescription,
FieldLabel,
} from "@/components/ui/field";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
export function RadioGroupDescription() {
return (
<RadioGroup className="w-fit" defaultValue="comfortable">
<Field orientation="horizontal">
<RadioGroupItem id="desc-r1" value="default" />
<FieldContent>
<FieldLabel htmlFor="desc-r1">Default</FieldLabel>
<FieldDescription>
Standard spacing for most use cases.
</FieldDescription>
</FieldContent>
</Field>
<Field orientation="horizontal">
<RadioGroupItem id="desc-r2" value="comfortable" />
<FieldContent>
<FieldLabel htmlFor="desc-r2">Comfortable</FieldLabel>
<FieldDescription>More space between elements.</FieldDescription>
</FieldContent>
</Field>
<Field orientation="horizontal">
<RadioGroupItem id="desc-r3" value="compact" />
<FieldContent>
<FieldLabel htmlFor="desc-r3">Compact</FieldLabel>
<FieldDescription>
Minimal spacing for dense layouts.
</FieldDescription>
</FieldContent>
</Field>
</RadioGroup>
);
}Choice card
Wrap each option in FieldLabel to make the entire card clickable.
import {
Field,
FieldContent,
FieldDescription,
FieldLabel,
FieldTitle,
} from "@/components/ui/field";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
export function RadioGroupChoiceCard() {
return (
<RadioGroup className="max-w-sm" defaultValue="plus">
<FieldLabel htmlFor="plus-plan">
<Field orientation="horizontal">
<FieldContent>
<FieldTitle>Plus</FieldTitle>
<FieldDescription>
For individuals and small teams.
</FieldDescription>
</FieldContent>
<RadioGroupItem id="plus-plan" value="plus" />
</Field>
</FieldLabel>
<FieldLabel htmlFor="pro-plan">
<Field orientation="horizontal">
<FieldContent>
<FieldTitle>Pro</FieldTitle>
<FieldDescription>For growing businesses.</FieldDescription>
</FieldContent>
<RadioGroupItem id="pro-plan" value="pro" />
</Field>
</FieldLabel>
<FieldLabel htmlFor="enterprise-plan">
<Field orientation="horizontal">
<FieldContent>
<FieldTitle>Enterprise</FieldTitle>
<FieldDescription>
For large teams and enterprises.
</FieldDescription>
</FieldContent>
<RadioGroupItem id="enterprise-plan" value="enterprise" />
</Field>
</FieldLabel>
</RadioGroup>
);
}Fieldset
Use FieldSet and FieldLegend for a labelled group.
import {
Field,
FieldDescription,
FieldLabel,
FieldLegend,
FieldSet,
} from "@/components/ui/field";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
export function RadioGroupFieldset() {
return (
<FieldSet className="max-w-xs">
<FieldLegend variant="label">Subscription Plan</FieldLegend>
<FieldDescription>
Yearly and lifetime plans offer significant savings.
</FieldDescription>
<RadioGroup defaultValue="monthly">
<Field orientation="horizontal">
<RadioGroupItem id="plan-monthly" value="monthly" />
<FieldLabel className="font-normal" htmlFor="plan-monthly">
Monthly ($9.99/month)
</FieldLabel>
</Field>
<Field orientation="horizontal">
<RadioGroupItem id="plan-yearly" value="yearly" />
<FieldLabel className="font-normal" htmlFor="plan-yearly">
Yearly ($99.99/year)
</FieldLabel>
</Field>
<Field orientation="horizontal">
<RadioGroupItem id="plan-lifetime" value="lifetime" />
<FieldLabel className="font-normal" htmlFor="plan-lifetime">
Lifetime ($299.99)
</FieldLabel>
</Field>
</RadioGroup>
</FieldSet>
);
}Disabled
import { Field, FieldLabel } from "@/components/ui/field";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
export function RadioGroupDisabled() {
return (
<RadioGroup className="w-fit" defaultValue="option2">
<Field data-disabled orientation="horizontal">
<RadioGroupItem disabled id="disabled-1" value="option1" />
<FieldLabel className="font-normal" htmlFor="disabled-1">
Disabled
</FieldLabel>
</Field>
<Field orientation="horizontal">
<RadioGroupItem id="disabled-2" value="option2" />
<FieldLabel className="font-normal" htmlFor="disabled-2">
Option 2
</FieldLabel>
</Field>
<Field orientation="horizontal">
<RadioGroupItem id="disabled-3" value="option3" />
<FieldLabel className="font-normal" htmlFor="disabled-3">
Option 3
</FieldLabel>
</Field>
</RadioGroup>
);
}Invalid
Mark each item with aria-invalid and its Field wrapper with data-invalid.
import {
Field,
FieldDescription,
FieldLabel,
FieldLegend,
FieldSet,
} from "@/components/ui/field";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
export function RadioGroupInvalid() {
return (
<FieldSet className="max-w-xs">
<FieldLegend variant="label">Notification Preferences</FieldLegend>
<FieldDescription>
Choose how you want to receive notifications.
</FieldDescription>
<RadioGroup defaultValue="email">
<Field data-invalid orientation="horizontal">
<RadioGroupItem aria-invalid id="invalid-email" value="email" />
<FieldLabel className="font-normal" htmlFor="invalid-email">
Email only
</FieldLabel>
</Field>
<Field data-invalid orientation="horizontal">
<RadioGroupItem aria-invalid id="invalid-sms" value="sms" />
<FieldLabel className="font-normal" htmlFor="invalid-sms">
SMS only
</FieldLabel>
</Field>
<Field data-invalid orientation="horizontal">
<RadioGroupItem aria-invalid id="invalid-both" value="both" />
<FieldLabel className="font-normal" htmlFor="invalid-both">
Both Email & SMS
</FieldLabel>
</Field>
</RadioGroup>
</FieldSet>
);
}In Context
Plan selector
"use client";
import { Label } from "@/components/ui/label";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
export function RadioGroupPlan() {
return (
<RadioGroup className="mx-auto w-fit max-w-full" defaultValue="pro">
<div className="flex items-center gap-2">
<RadioGroupItem id="free" value="free" />
<Label htmlFor="free">Free</Label>
</div>
<div className="flex items-center gap-2">
<RadioGroupItem id="pro" value="pro" />
<Label htmlFor="pro">Pro</Label>
</div>
<div className="flex items-center gap-2">
<RadioGroupItem id="team" value="team" />
<Label htmlFor="team">Team</Label>
</div>
</RadioGroup>
);
}API Reference
RadioGroup
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | — | Controlled selected value. |
defaultValue | string | — | Initial selected value when uncontrolled. |
onValueChange | function | — | Called when the selection changes. |
disabled | boolean | false | Disable the entire group. |
orientation | horizontalvertical | vertical | Arrow key navigation axis. |
RadioGroupItem
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | — | Unique value returned when this item is selected. |
disabled | boolean | false | Prevent selection. |
Controlled
const [value, setValue] = React.useState("")
<RadioGroup value={value} onValueChange={setValue}>{/* ... */}</RadioGroup>Keyboard
| Key | Action |
|---|---|
Space | Select the focused option |
↑ / ↓ | Move between options |
Data Attributes
| Attribute | Values |
|---|---|
data-slot | radio-group, radio-group-item |
data-state | checked | unchecked |
data-disabled | true |
data-orientation | horizontal | vertical |
Accessibility
- Follows the WAI-ARIA radio group pattern.
- Arrow keys move the selection within the group.
- Each item must have a matching
LabelwithhtmlFor. - Invalid state is conveyed via
aria-invalidon the item anddata-invalidon the wrapper.
Best Practices
- Use for exclusive choices. Independent toggles belong in Checkbox.
- Always set a default. An empty radio group leaves the user unsure of the starting state.
- Stack vertically for forms. Horizontal layouts are hard to read past three options.
- Pair with a visible label. Every option needs a matching
Label htmlFor.