CheckboxInput

A checkbox input with label, description, and validation support.

Examples

Default

Accept terms

<CheckboxInput label="Accept terms" value={false} />

Checked

Accept terms

<CheckboxInput label="Accept terms" value />

Indeterminate

Accept terms

<CheckboxInput label="Accept terms" value="indeterminate" />

With Description

Subscribe to newsletterReceive weekly product updates and announcements.

<CheckboxInput
  label="Subscribe to newsletter"
  value={false}
  description="Receive weekly product updates and announcements."
/>

With Label Tooltip

Accept terms

You must accept the terms before continuing.

Accept terms

You must accept the terms before continuing.

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

  return (
    <CheckboxInput
      {...args}
      onChange={checked => setValue(checked)}
      value={value}
    />
  );
}

<div
  className={css({
    display: 'flex',
    flexDirection: 'column',
    gap: '4',
  })}>
  <CheckboxStory {...args} isDisabled={false} />
  <CheckboxStory {...args} isDisabled />
</div>

With Padding

Accept terms

<CheckboxInput label="Accept terms" value={false} padding={2} />

With Link In Label

I agree to the terms and conditions

<CheckboxInput
  label={( <> I agree to the <Link href="/terms">terms and conditions</Link> </> )}
  value={false}
/>

Small

Accept terms

<CheckboxInput label="Accept terms" value={false} size="sm" />

Large

Accept terms

<CheckboxInput label="Accept terms" value={false} size="lg" />

Disabled

Accept terms

<CheckboxInput label="Accept terms" value isDisabled />

Read Only

Accept terms

<CheckboxInput label="Accept terms" value isReadOnly />

Loading

Accept terms

<CheckboxInput label="Accept terms" value isLoading />

Required

Accept terms · Required

<CheckboxInput label="Accept terms" value={false} isRequired />

Error

Accept terms

You must accept the terms to continue.

<CheckboxInput
  label="Accept terms"
  value={false}
  status={{message: 'You must accept the terms to continue.', type: 'error'}}
/>

Warning

Accept terms

This setting may affect performance.

<CheckboxInput
  label="Accept terms"
  value
  status={{message: 'This setting may affect performance.', type: 'warning'}}
/>

Success

Accept terms

Preference saved.

<CheckboxInput
  label="Accept terms"
  value
  status={{message: 'Preference saved.', type: 'success'}}
/>

With Icon

Enable notifications

<CheckboxInput
  label="Enable notifications"
  value={false}
  startContent={<Icon color="secondary" icon={Bell} size="sm" />}
/>

End Content Inline

Beta featuresNew

<CheckboxInput
  label="Beta features"
  value={false}
  endContent={<Badge color="blue" label="New" />}
  endContentPosition="inline"
/>

End Content End

Beta featuresNew

<CheckboxInput
  label="Beta features"
  value={false}
  endContent={<Badge color="blue" label="New" />}
  endContentPosition="end"
/>

API

CheckboxInput

A checkbox input with label, description, and validation support.

When isOptional: false, isRequired: false

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 root element.
data-testid	string	—	Test ID applied to the input element.
description	ReactNode	—	Supporting text rendered below the label.
endContent	ReactNode	—	Content rendered after the label.
endContentPosition	'end' | 'inline'	'inline'	Where to place endContent within the item. 'end' pushes it to the trailing edge; 'inline' keeps it next to the label.
htmlName	string	—	HTML name attribute for native form submission.
htmlValue	string	—	HTML value attribute for native form submission.
isDisabled	boolean	false	Whether the checkbox is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the checkbox is in a loading state.
isReadOnly	boolean	false	Whether the checkbox is read-only.
label*	ReactNode	—	Field label content.
labelIcon	IconComponent	—	Optional content shown before the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input loses focus.
onChange*	(checked: boolean, event: ChangeEvent<HTMLInputElement>) => void	—	Called when the checked state changes.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input receives focus.
padding	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	0	Inner padding around the checkbox row.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the input element.
size	"sm" | "md" | "lg"	'md'	Visual size of the checkbox.
startContent	ReactNode	—	Content rendered after the checkbox control and before the label.
status	InputStatus	—	Validation status displayed below the checkbox.
style	CSSProperties	—	Inline styles applied to the root element.
value*	boolean | "indeterminate"	—	Current checked state: true, false, or 'indeterminate'.
width	WidthValue	'full'	Width of the checkbox item. Numbers are pixels, strings are used as-is, 'full' fills the container.
isOptional	false	—
isRequired	false	—

When isOptional: true, isRequired: false

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 root element.
data-testid	string	—	Test ID applied to the input element.
description	ReactNode	—	Supporting text rendered below the label.
endContent	ReactNode	—	Content rendered after the label.
endContentPosition	'end' | 'inline'	'inline'	Where to place endContent within the item. 'end' pushes it to the trailing edge; 'inline' keeps it next to the label.
htmlName	string	—	HTML name attribute for native form submission.
htmlValue	string	—	HTML value attribute for native form submission.
isDisabled	boolean	false	Whether the checkbox is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the checkbox is in a loading state.
isReadOnly	boolean	false	Whether the checkbox is read-only.
label*	ReactNode	—	Field label content.
labelIcon	IconComponent	—	Optional content shown before the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input loses focus.
onChange*	(checked: boolean, event: ChangeEvent<HTMLInputElement>) => void	—	Called when the checked state changes.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input receives focus.
padding	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	0	Inner padding around the checkbox row.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the input element.
size	"sm" | "md" | "lg"	'md'	Visual size of the checkbox.
startContent	ReactNode	—	Content rendered after the checkbox control and before the label.
status	InputStatus	—	Validation status displayed below the checkbox.
style	CSSProperties	—	Inline styles applied to the root element.
value*	boolean | "indeterminate"	—	Current checked state: true, false, or 'indeterminate'.
width	WidthValue	'full'	Width of the checkbox item. Numbers are pixels, strings are used as-is, 'full' fills the container.
isOptional*	true	—
isRequired	false	—

When isOptional: false, isRequired: true

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 root element.
data-testid	string	—	Test ID applied to the input element.
description	ReactNode	—	Supporting text rendered below the label.
endContent	ReactNode	—	Content rendered after the label.
endContentPosition	'end' | 'inline'	'inline'	Where to place endContent within the item. 'end' pushes it to the trailing edge; 'inline' keeps it next to the label.
htmlName	string	—	HTML name attribute for native form submission.
htmlValue	string	—	HTML value attribute for native form submission.
isDisabled	boolean	false	Whether the checkbox is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the checkbox is in a loading state.
isReadOnly	boolean	false	Whether the checkbox is read-only.
label*	ReactNode	—	Field label content.
labelIcon	IconComponent	—	Optional content shown before the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input loses focus.
onChange*	(checked: boolean, event: ChangeEvent<HTMLInputElement>) => void	—	Called when the checked state changes.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input receives focus.
padding	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	0	Inner padding around the checkbox row.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the input element.
size	"sm" | "md" | "lg"	'md'	Visual size of the checkbox.
startContent	ReactNode	—	Content rendered after the checkbox control and before the label.
status	InputStatus	—	Validation status displayed below the checkbox.
style	CSSProperties	—	Inline styles applied to the root element.
value*	boolean | "indeterminate"	—	Current checked state: true, false, or 'indeterminate'.
width	WidthValue	'full'	Width of the checkbox item. Numbers are pixels, strings are used as-is, 'full' fills the container.
isOptional	false	—
isRequired*	true	—