For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Radio Group

A set of checkable buttons where only one can be selected at a time.

radio-group.tsx
"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

Usage

radio-group.tsx
import { Label } from "@/components/ui/label";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
<DocsBaseSwitcher base="web" component="radio-group" className="mb-6" />
tsx
<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
└── RadioGroupItem

Examples

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.

radio-group-description.tsx
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.

radio-group-choice-card.tsx
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.

Subscription Plan

Yearly and lifetime plans offer significant savings.

radio-group-fieldset.tsx
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

radio-group-disabled.tsx
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.

Notification Preferences

Choose how you want to receive notifications.

radio-group-invalid.tsx
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

radio-group-plan.tsx
"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

PropTypeDefaultDescription
valuestring—Controlled selected value.
defaultValuestring—Initial selected value when uncontrolled.
onValueChangefunction—Called when the selection changes.
disabledbooleanfalseDisable the entire group.
orientation
horizontalvertical
verticalArrow key navigation axis.

RadioGroupItem

PropTypeDefaultDescription
valuestring—Unique value returned when this item is selected.
disabledbooleanfalsePrevent selection.

Controlled

tsx
const [value, setValue] = React.useState("")
<RadioGroup value={value} onValueChange={setValue}>{/* ... */}</RadioGroup>

Keyboard

KeyAction
SpaceSelect the focused option
↑ / ↓Move between options

Data Attributes

AttributeValues
data-slotradio-group, radio-group-item
data-statechecked | unchecked
data-disabledtrue
data-orientationhorizontal | vertical

Accessibility

  • Follows the WAI-ARIA radio group pattern.
  • Arrow keys move the selection within the group.
  • Each item must have a matching Label with htmlFor.
  • Invalid state is conveyed via aria-invalid on the item and data-invalid on 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.
  • Checkbox — multiple choice
  • Select — compact single choice
  • Field — label + error