Checkbox

Accept terms and conditions

const [checked, setChecked] = useState(false);

<Checkbox
  label="Accept terms and conditions"
  checked={checked}
  onCheckedChange={setChecked}
/>

Installation

Barrel

import { Checkbox } from "@cloudflare/kumo";

Granular

import { Checkbox } from "@cloudflare/kumo/components/checkbox";

Usage

import { Checkbox } from "@cloudflare/kumo";

export default function Example() {
  return <Checkbox label="Accept terms" />;
}

Examples

Default

Checkbox with built-in label. The label automatically displays in a horizontal layout (checkbox before label).

Enable notifications

const [checked, setChecked] = useState(false);

<Checkbox
  label="Enable notifications"
  checked={checked}
  onCheckedChange={setChecked}
/>

Checked

I agree

const [checked, setChecked] = useState(true);

<Checkbox
  label="I agree"
  checked={checked}
  onCheckedChange={setChecked}
/>

Indeterminate

Used for "select all" patterns when some but not all items are selected.

Select all

const [indeterminate, setIndeterminate] = useState(true);

<Checkbox
  label="Select all"
  indeterminate={indeterminate}
  onCheckedChange={() => setIndeterminate(false)}
/>

Label First Layout

Use controlFirst={false} to place the label before the checkbox.

Remember me

const [checked, setChecked] = useState(false);

<Checkbox
  label="Remember me"
  controlFirst={false}
  checked={checked}
  onCheckedChange={setChecked}
/>

Disabled

Disabled option

<Checkbox label="Disabled option" disabled />

Error

Error variant provides visual styling (red ring). For error messages, use Checkbox.Group.

Invalid option

<Checkbox label="Invalid option" variant="error" />

Checkbox Group

Group multiple checkboxes with a legend, description, and shared error messages. Uses Checkbox.Group and Checkbox.Item.

Email preferences

Email notificationsSMS notificationsPush notifications

Choose how you'd like to receive updates

<Checkbox.Group
  legend="Email preferences"
  description="Choose how you'd like to receive updates"
  value={preferences}
  onValueChange={setPreferences}
>
  <Checkbox.Item value="email" label="Email notifications" />
  <Checkbox.Item value="sms" label="SMS notifications" />
  <Checkbox.Item value="push" label="Push notifications" />
</Checkbox.Group>

Checkbox Group with Error

Show validation errors at the group level. Error replaces description when present.

Required preferences

EmailSMS

Please select at least one notification method

<Checkbox.Group
  legend="Required preferences"
  error="Please select at least one notification method"
  value={[]}
  onValueChange={() => {}}
>
  <Checkbox.Item value="email" label="Email" variant="error" />
  <Checkbox.Item value="sms" label="SMS" variant="error" />
</Checkbox.Group>

API Reference

Single checkbox component with built-in label and horizontal layout.

Prop	Type	Default	Description
variant	`"default" \| "error"`	`"default"`	Visual variant: "default" or "error" for validation failures (visual only, no error text)
label	`ReactNode`	-	Label content for the checkbox (enables built-in Field wrapper) - can be a string or any React node
labelTooltip	`ReactNode`	-	Tooltip content to display next to the label via an info icon
controlFirst	`boolean`	-	When true (default), checkbox appears before label. When false, label appears before checkbox.
checked	`boolean`	-	Whether the checkbox is checked (controlled)
indeterminate	`boolean`	-	Whether the checkbox is in indeterminate state
disabled	`boolean`	-	Whether the checkbox is disabled
name	`string`	-	Name for form submission
required	`boolean`	-	Whether the field is required
className	`string`	-	Additional class name
onValueChange	`(checked: boolean) => void`	-	Callback when checkbox value changes

Checkbox.Group

Wrapper for multiple checkboxes with legend, description, and error support.

Prop	Type	Default
legend*	`string`	-
children*	`ReactNode`	-
error	`string`	-
description	`ReactNode`	-
value	`string[]`	-
allValues	`string[]`	-
disabled	`boolean`	-
controlFirst	`boolean`	-
className	`string`	-

Checkbox.Item

Individual checkbox within Checkbox.Group.

Prop	Type	Default

No component-specific props. Accepts standard HTML attributes.

Accessibility

Label Requirement

Single checkboxes require a label prop or aria-label for accessibility. Missing labels trigger console warnings in development.

Keyboard Navigation

Space toggles the checkbox. Tab moves focus between checkboxes.

Screen Readers

Checkbox.Group uses semantic <fieldset> and <legend> elements for proper grouping announcement.