RadioGroup

A controlled radio group for single-value selection.

Examples

Default

Notification preference

EmailBest for detailed updates.

SMS

Push

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  htmlName="notificationPreference"
  value="email"
/>

Horizontal

Notification preference

EmailBest for detailed updates.

SMS

Push

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  htmlName="notificationPreference"
  value="email"
  orientation="horizontal"
/>

Small

Notification preference

EmailBest for detailed updates.

SMS

Push

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  htmlName="notificationPreference"
  value="email"
  size="sm"
/>

Large

Notification preference

EmailBest for detailed updates.

SMS

Push

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  htmlName="notificationPreference"
  value="email"
  size="lg"
/>

Disabled

Notification preference

EmailBest for detailed updates.

SMS

Push

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  htmlName="notificationPreference"
  value="email"
  isDisabled
/>

Read Only

Notification preference

EmailBest for detailed updates.

SMS

Push

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  htmlName="notificationPreference"
  value="email"
  isReadOnly
/>

Item Disabled

Notification preference

Email

SMS

Push

function ItemDisabledStory(args: RadioGroupProps): React.JSX.Element {
  const [value, setValue] = useState(args.value);

  return (
    <RadioGroup {...args} onChange={setValue} value={value}>
      <RadioGroupItem label="Email" value="email" />
      <RadioGroupItem isDisabled label="SMS" value="sms" />
      <RadioGroupItem label="Push" value="push" />
    </RadioGroup>
  );
}

<ItemDisabledStory {...args} />

Required

Notification preference · Required

EmailBest for detailed updates.

SMS

Push

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  htmlName="notificationPreference"
  value="email"
  isRequired
/>

Optional

Notification preference · Optional

EmailBest for detailed updates.

SMS

Push

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  htmlName="notificationPreference"
  value="email"
  isOptional
/>

Error

Notification preference

EmailBest for detailed updates.

SMS

Push

Select a notification preference.

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  htmlName="notificationPreference"
  value="email"
  status={{message: 'Select a notification preference.', type: 'error'}}
/>

With End Content

Notification preference

EmailRecommended

SMS

Push

function WithEndContentStory(args: RadioGroupProps): React.JSX.Element {
  const [value, setValue] = useState(args.value);

  return (
    <RadioGroup {...args} onChange={setValue} value={value}>
      <RadioGroupItem
        endContent={<Badge color="blue" label="Recommended" />}
        label="Email"
        value="email"
      />
      <RadioGroupItem label="SMS" value="sms" />
      <RadioGroupItem label="Push" value="push" />
    </RadioGroup>
  );
}

<WithEndContentStory {...args} />

With Icons

Notification preference

Email

SMS

Push

function WithIconsStory(args: RadioGroupProps): React.JSX.Element {
  const [value, setValue] = useState(args.value);

  return (
    <RadioGroup {...args} onChange={setValue} value={value}>
      <RadioGroupItem
        label="Email"
        startContent={<Icon color="secondary" icon={Mail} size="sm" />}
        value="email"
      />
      <RadioGroupItem
        label="SMS"
        startContent={<Icon color="secondary" icon={MessageSquare} size="sm" />}
        value="sms"
      />
      <RadioGroupItem
        label="Push"
        startContent={<Icon color="secondary" icon={Bell} size="sm" />}
        value="push"
      />
    </RadioGroup>
  );
}

<WithIconsStory {...args} />

Warning

Notification preference

EmailBest for detailed updates.

SMS

Push

SMS may incur carrier charges.

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  htmlName="notificationPreference"
  value="email"
  status={{message: 'SMS may incur carrier charges.', type: 'warning'}}
/>

Success

Notification preference

EmailBest for detailed updates.

SMS

Push

Preference saved.

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  htmlName="notificationPreference"
  value="email"
  status={{message: 'Preference saved.', type: 'success'}}
/>

API

RadioGroup

A controlled radio group for single-value selection.

When isOptional: false, isRequired: false

Prop	Type	Default	Description
children*	ReactNode	—	Radio list items to render.
className	string	—	Additional CSS class names applied to the field root.
data-testid	string	—	Test ID applied to the field root.
description	ReactNode	—	Supporting text displayed below the label.
htmlName	string	—	HTML name attribute shared by radio inputs for native form submission.
isDisabled	boolean	false	Whether all radio items are disabled.
isReadOnly	boolean	false	Whether the selected value can be changed by the user. Read-only radio items remain enabled for form submission but cannot be focused or activated.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the radio group.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onChange*	(value: string) => void	—	Callback fired when the selected value changes. Memoize with useCallback to avoid unnecessary re-renders of radio items.
orientation	"horizontal" | "vertical"	'vertical'	Layout direction of the radio items.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
size	"sm" | "md" | "lg"	'md'	Size of the radio controls.
status	InputStatus	—	Validation status displayed below the group.
style	CSSProperties	—	Inline styles applied to the field root.
value*	string	—	The currently selected value.
isOptional	false	—
isRequired	false	—

When isOptional: true, isRequired: false

Prop	Type	Default	Description
children*	ReactNode	—	Radio list items to render.
className	string	—	Additional CSS class names applied to the field root.
data-testid	string	—	Test ID applied to the field root.
description	ReactNode	—	Supporting text displayed below the label.
htmlName	string	—	HTML name attribute shared by radio inputs for native form submission.
isDisabled	boolean	false	Whether all radio items are disabled.
isReadOnly	boolean	false	Whether the selected value can be changed by the user. Read-only radio items remain enabled for form submission but cannot be focused or activated.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the radio group.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onChange*	(value: string) => void	—	Callback fired when the selected value changes. Memoize with useCallback to avoid unnecessary re-renders of radio items.
orientation	"horizontal" | "vertical"	'vertical'	Layout direction of the radio items.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
size	"sm" | "md" | "lg"	'md'	Size of the radio controls.
status	InputStatus	—	Validation status displayed below the group.
style	CSSProperties	—	Inline styles applied to the field root.
value*	string	—	The currently selected value.
isOptional*	true	—
isRequired	false	—

When isOptional: false, isRequired: true

Prop	Type	Default	Description
children*	ReactNode	—	Radio list items to render.
className	string	—	Additional CSS class names applied to the field root.
data-testid	string	—	Test ID applied to the field root.
description	ReactNode	—	Supporting text displayed below the label.
htmlName	string	—	HTML name attribute shared by radio inputs for native form submission.
isDisabled	boolean	false	Whether all radio items are disabled.
isReadOnly	boolean	false	Whether the selected value can be changed by the user. Read-only radio items remain enabled for form submission but cannot be focused or activated.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the radio group.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onChange*	(value: string) => void	—	Callback fired when the selected value changes. Memoize with useCallback to avoid unnecessary re-renders of radio items.
orientation	"horizontal" | "vertical"	'vertical'	Layout direction of the radio items.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
size	"sm" | "md" | "lg"	'md'	Size of the radio controls.
status	InputStatus	—	Validation status displayed below the group.
style	CSSProperties	—	Inline styles applied to the field root.
value*	string	—	The currently selected value.
isOptional	false	—
isRequired*	true	—

RadioGroupItem

An individual radio option within a `RadioGroup`.

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the item root.
data-testid	string	—	Test ID applied to the item root.
description	ReactNode	—	Supporting text displayed below the item label.
endContent	ReactNode	—	Content rendered after the label and description.
isDisabled	boolean	false	Whether this radio item is disabled.
label*	string	—	Label text for the radio item.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the item root.
startContent	ReactNode	—	Content rendered after the radio control and before the label.
style	CSSProperties	—	Inline styles applied to the item root.
value*	string	—	Value represented by this radio item.