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

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 preferenceRequired

EmailBest for detailed updates.

SMS

Push

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

Optional

Notification preferenceOptional

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

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.
`labelEnd`	`ReactNode`	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when `isLabelHidden` is true.
`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.
`labelEnd`	`ReactNode`	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when `isLabelHidden` is true.
`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.
`labelEnd`	`ReactNode`	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when `isLabelHidden` is true.
`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
`aria-label`	`string`	—	Accessible name applied to the radio input, overriding the label text. Use when a rich label has no useful text. Include any visible label wording.
`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`*	`ReactNode`	—	Label content for the radio item. Supports noninteractive formatting, decorative icons, and badges. Keep links and buttons in the content slots. The label's text supplies the accessible name unless `aria-label` is set.
`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.