Radio Group

Choose one option from a set of mutually exclusive values.

View component source ↗

Preview

Example

A minimal example to get started.

ComfortableCompact

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/radio-group.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

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

export default function Example() {
  return (
    <RadioGroup defaultValue="comfortable" aria-label="Density">
      <label className="flex items-center gap-2 text-sm">
        <RadioGroupItem value="comfortable" />
        Comfortable
      </label>
      <label className="flex items-center gap-2 text-sm">
        <RadioGroupItem value="compact" />
        Compact
      </label>
    </RadioGroup>
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

RadioGroup

RadioGroup properties
Prop	Type	Default	Description
`disabled`	boolean \| undefined boolean \| undefined	`false`	Whether the component should ignore user interaction.
`readOnly`	boolean \| undefined boolean \| undefined	`false`	Whether the user should be unable to select a different radio button in the group.
`required`	boolean \| undefined boolean \| undefined	`false`	Whether the user must choose a value before submitting a form.
`name`	string \| undefined string \| undefined	`—`	Identifies the field when a form is submitted.
`form`	string \| undefined string \| undefined	`—`	Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form.
`value`	any any	`—`	The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead.
`defaultValue`	any any	`—`	The uncontrolled value of the radio button that should be initially selected. To render a controlled radio group, use the `value` prop instead.
`onValueChange`	((value: any, eventDetails: RadioGroupPrimitive.ChangeEventDetails) => void) \| undefined ((value: any, eventDetails: RadioGroupPrimitive.ChangeEventDetails) => void) \| undefined	`—`	Callback fired when the value changes.
`inputRef`	React.Ref<HTMLInputElement> \| undefined React.Ref<HTMLInputElement> \| undefined	`—`	A ref to access the hidden input element.
`className`	string \| ((state: RadioGroupState) => string \| undefined) \| undefined string \| ((state: RadioGroupState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`style`	React.CSSProperties \| ((state: RadioGroupState) => React.CSSProperties \| undefined) \| unde… React.CSSProperties \| ((state: RadioGroupState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLDivElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLDivElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void) \| undefined ((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, RadioGroupState> \| undefined	`—`	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

RadioGroupItem

RadioGroupItem properties
Prop	Type	Default	Description
`value`Required	any any	`—`	The unique identifying value of the radio in a group.
`disabled`	boolean \| undefined boolean \| undefined	`—`	Whether the component should ignore user interaction.
`required`	boolean \| undefined boolean \| undefined	`—`	Whether the user must choose a value before submitting a form.
`readOnly`	boolean \| undefined boolean \| undefined	`—`	Whether the user should be unable to select the radio button.
`inputRef`	React.Ref<HTMLInputElement> \| undefined React.Ref<HTMLInputElement> \| undefined	`—`	A ref to access the hidden input element.
`nativeButton`	boolean \| undefined boolean \| undefined	`false`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
`className`	string \| ((state: RadioRootState) => string \| undefined) \| undefined string \| ((state: RadioRootState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`style`	React.CSSProperties \| ((state: RadioRootState) => React.CSSProperties \| undefined) \| undef… React.CSSProperties \| ((state: RadioRootState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.
`ref`	React.Ref<HTMLSpanElement> \| undefined React.Ref<HTMLSpanElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLSpanElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLSpanElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLSpanElement, MouseEvent>>) => void) \| undefined ((event: BaseUIEvent<React.MouseEvent<HTMLSpanElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, RadioRootState> \| undefined	`—`	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Usage notes

Give the group a clear label and each item a visible option name. Use defaultValue or controlled value to establish the selection.