CheckboxGroup

A controlled checkbox group for multi-value selection.

Examples

Default

Notification channelsChoose any channels that apply.

EmailBest for detailed updates.

SMS

Push

<CheckboxGroup
  description="Choose any channels that apply."
  label="Notification channels"
  value={['email', 'push']}
/>

Horizontal

Notification channelsChoose any channels that apply.

EmailBest for detailed updates.

SMS

Push

<CheckboxGroup
  description="Choose any channels that apply."
  label="Notification channels"
  value={['email', 'push']}
  orientation="horizontal"
/>

Wrapping Row

TeamsChoose the teams that should receive access.

Design

Engineering

Marketing

Operations

Support

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

  return (
    <CheckboxGroup
      {...args}
      onChange={setValue}
      orientation="horizontal"
      style={{maxWidth: 420}}
      value={value}>
      <CheckboxGroupItem label="Design" value="design" />
      <CheckboxGroupItem label="Engineering" value="engineering" />
      <CheckboxGroupItem label="Marketing" value="marketing" />
      <CheckboxGroupItem label="Operations" value="operations" />
      <CheckboxGroupItem label="Support" value="support" />
    </CheckboxGroup>
  );
}

<WrappingRowStory {...args} />

Small

Notification channelsChoose any channels that apply.

EmailBest for detailed updates.

SMS

Push

<CheckboxGroup
  description="Choose any channels that apply."
  label="Notification channels"
  value={['email', 'push']}
  size="sm"
/>

Large

Notification channelsChoose any channels that apply.

EmailBest for detailed updates.

SMS

Push

<CheckboxGroup
  description="Choose any channels that apply."
  label="Notification channels"
  value={['email', 'push']}
  size="lg"
/>

Disabled

Notification channelsChoose any channels that apply.

EmailBest for detailed updates.

SMS

Push

<CheckboxGroup
  description="Choose any channels that apply."
  label="Notification channels"
  value={['email', 'push']}
  isDisabled
/>

Item Disabled

Notification channelsChoose any channels that apply.

Email

SMS

Push

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

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

<ItemDisabledStory {...args} />

Required

Notification channels · RequiredChoose any channels that apply.

EmailBest for detailed updates.

SMS

Push

<CheckboxGroup
  description="Choose any channels that apply."
  label="Notification channels"
  value={['email', 'push']}
  isRequired
/>

Optional

Notification channels · OptionalChoose any channels that apply.

EmailBest for detailed updates.

SMS

Push

<CheckboxGroup
  description="Choose any channels that apply."
  label="Notification channels"
  value={['email', 'push']}
  isOptional
/>

Error

Notification channelsChoose any channels that apply.

EmailBest for detailed updates.

SMS

Push

Select at least one notification channel.

<CheckboxGroup
  description="Choose any channels that apply."
  label="Notification channels"
  value={[]}
  status={{ message: 'Select at least one notification channel.', type: 'error', }}
/>

With End Content

Notification channelsChoose any channels that apply.

EmailRecommended

SMS

Push

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

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

<WithEndContentStory {...args} />

With Icons

Notification channelsChoose any channels that apply.

Email

SMS

Push

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

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

<WithIconsStory {...args} />

Warning

Notification channelsChoose any channels that apply.

EmailBest for detailed updates.

SMS

Push

SMS may incur carrier charges.

<CheckboxGroup
  description="Choose any channels that apply."
  label="Notification channels"
  value={['email', 'push']}
  status={{message: 'SMS may incur carrier charges.', type: 'warning'}}
/>

Success

Notification channelsChoose any channels that apply.

EmailBest for detailed updates.

SMS

Push

Preferences saved.

<CheckboxGroup
  description="Choose any channels that apply."
  label="Notification channels"
  value={['email', 'push']}
  status={{message: 'Preferences saved.', type: 'success'}}
/>

Read Only

Notification channelsChoose any channels that apply.

EmailBest for detailed updates.

SMS

Push

<CheckboxGroup
  description="Choose any channels that apply."
  label="Notification channels"
  value={['email', 'push']}
  isReadOnly
/>

API

CheckboxGroup

A controlled checkbox group for multi-value selection.

When isOptional: false, isRequired: false

Prop	Type	Default	Description
children*	ReactNode	—	Checkbox 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 checkbox inputs for native form submission.
isDisabled	boolean	false	Whether all checkbox items are disabled.
isReadOnly	boolean	false	Whether all checkbox items are read-only.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the checkbox 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 values change. Memoize with useCallback to avoid unnecessary re-renders of checkbox items.
orientation	"horizontal" | "vertical"	'vertical'	Layout direction of the checkbox items.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
size	"sm" | "md" | "lg"	'md'	Size of the checkbox controls.
status	InputStatus	—	Validation status displayed below the group.
style	CSSProperties	—	Inline styles applied to the field root.
value*	string[]	—	The currently selected values.
isOptional	false	—
isRequired	false	—

When isOptional: true, isRequired: false

Prop	Type	Default	Description
children*	ReactNode	—	Checkbox 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 checkbox inputs for native form submission.
isDisabled	boolean	false	Whether all checkbox items are disabled.
isReadOnly	boolean	false	Whether all checkbox items are read-only.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the checkbox 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 values change. Memoize with useCallback to avoid unnecessary re-renders of checkbox items.
orientation	"horizontal" | "vertical"	'vertical'	Layout direction of the checkbox items.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
size	"sm" | "md" | "lg"	'md'	Size of the checkbox controls.
status	InputStatus	—	Validation status displayed below the group.
style	CSSProperties	—	Inline styles applied to the field root.
value*	string[]	—	The currently selected values.
isOptional*	true	—
isRequired	false	—

When isOptional: false, isRequired: true

Prop	Type	Default	Description
children*	ReactNode	—	Checkbox 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 checkbox inputs for native form submission.
isDisabled	boolean	false	Whether all checkbox items are disabled.
isReadOnly	boolean	false	Whether all checkbox items are read-only.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the checkbox 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 values change. Memoize with useCallback to avoid unnecessary re-renders of checkbox items.
orientation	"horizontal" | "vertical"	'vertical'	Layout direction of the checkbox items.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
size	"sm" | "md" | "lg"	'md'	Size of the checkbox controls.
status	InputStatus	—	Validation status displayed below the group.
style	CSSProperties	—	Inline styles applied to the field root.
value*	string[]	—	The currently selected values.
isOptional	false	—
isRequired*	true	—

CheckboxGroupItem

An individual checkbox option within a `CheckboxGroup`.

Prop	Type	Default	Description
aria-label	string	—	Accessible name applied to the checkbox 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 input element.
description	ReactNode	—	Supporting text displayed below the item label.
endContent	ReactNode	—	Content rendered after the label and description.
endContentPosition	CheckboxInputProps['endContentPosition']	'inline'	Where to place endContent within the item.
isDisabled	boolean	false	Whether this checkbox item is disabled.
isReadOnly	boolean	false	Whether this checkbox item is read-only.
label*	ReactNode	—	Label content for the checkbox 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<HTMLInputElement>	—	Ref forwarded to the input element.
startContent	ReactNode	—	Content rendered after the checkbox control and before the label.
style	CSSProperties	—	Inline styles applied to the item root.
value*	string	—	Value represented by this checkbox item.