Checkbox

Accept terms and conditions

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

export function CheckboxBasicDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <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

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

export function CheckboxDefaultDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <Checkbox
      label="Enable notifications"
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

Checked

I agree

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

export function CheckboxCheckedDemo() {
  const [checked, setChecked] = useState(true);
  return (
    <Checkbox label="I agree" checked={checked} onCheckedChange={setChecked} />
  );
}

Indeterminate

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

Select all

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

export function CheckboxIndeterminateDemo() {
  const [indeterminate, setIndeterminate] = useState(true);
  return (
    <Checkbox
      label="Select all"
      indeterminate={indeterminate}
      onCheckedChange={setIndeterminate}
    />
  );
}

Label First Layout

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

Remember me

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

export function CheckboxLabelFirstDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <Checkbox
      label="Remember me"
      controlFirst={false}
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

Disabled

Disabled option

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

export function CheckboxDisabledDemo() {
  return <Checkbox label="Disabled option" disabled />;
}

Error

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

Invalid option

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

export function CheckboxErrorDemo() {
  return <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

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

export function CheckboxGroupDemo() {
  const [preferences, setPreferences] = useState<string[]>(["email"]);

  return (
    <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

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

export function CheckboxGroupErrorDemo() {
  return (
    <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.