--- title: Radio Group description: Choose one option from a related set. group: Components order: 54 --- A set of radio buttons where only one option can be selected. ```tsx import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group" export function Example() { return ( ) } ``` ## Installation ```bash npx @arctis-sh/@arctis-sh/ui@latest add radio-group ``` ## Usage ```tsx import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group" ``` ```tsx ``` ## Composition ```tree RadioGroup ├── RadioGroupItem └── RadioGroupItem ``` ## Basic Simple labeled options. Use `defaultValue` to set the initial uncontrolled value. ```tsx import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group" export function Example() { return ( ) } ``` ## Description Add a title and muted helper text when a short label is not enough. ```tsx import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group" export function Example() { return ( ) } ``` ## Card Wrap each option in a `Card` for a larger choice surface. Control selection with `value` and `onValueChange`; the selected card uses a filled surface. ```tsx import * as React from "react" import { Card, CardContent } from "@/components/ui/card" import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group" import { cn } from "@/lib/utils" export function Example() { const [plan, setPlan] = React.useState("pro") return ( ) } ``` ## Fieldset Group radios in a native `fieldset` and `legend` with helper text. ```tsx import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group" export function Example() { return (
Subscription Plan Yearly and lifetime plans offer significant savings.
) } ``` ## Disabled `disabled` on `RadioGroup` locks every item. Dim the labels so the list reads as inactive. ```tsx import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group" export function Example() { return ( ) } ``` ## Invalid Pass `aria-invalid` to the items for error styling, and use destructive text for their labels. ```tsx import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group" export function Example() { return (

Notification preferences

Choose how you want to receive notifications.

) } ``` ## API Reference ### RadioGroup | Prop | Type | Default | | --- | --- | --- | | value | string | — | | defaultValue | string | "" | | onValueChange | (value: string) => void | — | | disabled | boolean | — | | orientation | "vertical" \| "horizontal" | "vertical" | | className | string | — | ```tsx ``` ### RadioGroupItem Must be used inside `RadioGroup`. Arrow keys move selection within the group. Pass `aria-invalid` for validation styling. | Prop | Type | Default | | --- | --- | --- | | value | string | — | | disabled | boolean | — | | className | string | — | ```tsx ``` ## Source ```tsx "use client"; import { createContext, useCallback, useContext, useId, useMemo, useRef, useState, type ButtonHTMLAttributes, type HTMLAttributes, type KeyboardEvent, type MouseEvent, } from "react"; import { cn } from "@/lib/utils"; type RadioGroupContextValue = { value: string; disabled?: boolean; onValueChange: (value: string) => void; register: (value: string, el: HTMLButtonElement | null) => void; }; const RadioGroupContext = createContext(null); function useRadioGroup() { const context = useContext(RadioGroupContext); if (!context) { throw new Error("RadioGroupItem must be used within "); } return context; } type RadioGroupProps = Omit< HTMLAttributes, "defaultValue" | "onChange" > & { value?: string; defaultValue?: string; onValueChange?: (value: string) => void; disabled?: boolean; orientation?: "vertical" | "horizontal"; }; function RadioGroup({ className, value: valueProp, defaultValue = "", onValueChange, disabled, orientation = "vertical", children, onKeyDown, ...props }: RadioGroupProps) { const controlled = valueProp !== undefined; const [uncontrolled, setUncontrolled] = useState(defaultValue); const value = controlled ? valueProp : uncontrolled; const itemsRef = useRef(new Map()); const register = useCallback( (itemValue: string, el: HTMLButtonElement | null) => { if (el) itemsRef.current.set(itemValue, el); else itemsRef.current.delete(itemValue); }, [], ); const handleChange = useCallback( (next: string) => { if (!controlled) setUncontrolled(next); onValueChange?.(next); }, [controlled, onValueChange], ); const context = useMemo( () => ({ value, disabled, onValueChange: handleChange, register, }), [value, disabled, handleChange, register], ); function handleKeyDown(event: KeyboardEvent) { onKeyDown?.(event); if (event.defaultPrevented) return; const keys = [ "ArrowDown", "ArrowUp", "ArrowLeft", "ArrowRight", "Home", "End", ]; if (!keys.includes(event.key)) return; const items = Array.from(itemsRef.current.entries()).filter( ([, el]) => !el.disabled, ); if (!items.length) return; const currentIndex = items.findIndex(([itemValue]) => itemValue === value); let nextIndex = currentIndex; if (event.key === "Home") nextIndex = 0; else if (event.key === "End") nextIndex = items.length - 1; else if (event.key === "ArrowDown" || event.key === "ArrowRight") { nextIndex = currentIndex < 0 ? 0 : (currentIndex + 1) % items.length; } else if (event.key === "ArrowUp" || event.key === "ArrowLeft") { nextIndex = currentIndex < 0 ? items.length - 1 : (currentIndex - 1 + items.length) % items.length; } event.preventDefault(); const [nextValue, el] = items[nextIndex]!; handleChange(nextValue); el.focus(); } return (
{children}
); } type RadioGroupItemProps = Omit< ButtonHTMLAttributes, "value" | "children" | "role" > & { value: string; }; function RadioGroupItem({ className, value, disabled, id, onClick, ...props }: RadioGroupItemProps) { const group = useRadioGroup(); const generatedId = useId(); const itemId = id ?? generatedId; const checked = group.value === value; const isDisabled = Boolean(disabled || group.disabled); function handleClick(event: MouseEvent) { onClick?.(event); if (event.defaultPrevented || isDisabled) return; group.onValueChange(value); } return ( ); } export { RadioGroup, RadioGroupItem }; ```