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

<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

<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

<WithEndContentStory {...args} />

With Icons

Notification channelsChoose any channels that apply.

Email

SMS

Push

<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'}}
/>

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.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the checkbox group.
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.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the checkbox group.
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.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the checkbox group.
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
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.
label*	string	—	Label text for the checkbox item.
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.