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."
  value="email"
/>

Horizontal

Notification preference

EmailBest for detailed updates.

SMS

Push

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

Small

Notification preference

EmailBest for detailed updates.

SMS

Push

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

Large

Notification preference

EmailBest for detailed updates.

SMS

Push

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

Disabled

Notification preference

EmailBest for detailed updates.

SMS

Push

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

Item Disabled

Notification preference

Email

SMS

Push

<ItemDisabledStory {...args} />

Required

Notification preference · Required

EmailBest for detailed updates.

SMS

Push

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

Optional

Notification preference · Optional

EmailBest for detailed updates.

SMS

Push

<RadioGroup
  label="Notification preference"
  description="Choose one delivery channel."
  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."
  value="email"
  status={{message: 'Select a notification preference.', type: 'error'}}
/>

With End Content

Notification preference

EmailRecommended

SMS

Push

<WithEndContentStory {...args} />

With Icons

Notification preference

Email

SMS

Push

<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."
  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."
  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.
isDisabled	boolean	false	Whether all radio items are disabled.
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.
isDisabled	boolean	false	Whether all radio items are disabled.
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.
isDisabled	boolean	false	Whether all radio items are disabled.
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.