---
layout: ~/layouts/MdxDocLayout.astro
title: "Checkbox"
description: "A control that allows the user to toggle between checked and not checked. Features built-in label support with automatic horizontal layout."
sourceFile: "components/checkbox"
baseUIComponent: "checkbox"
---

import ComponentExample from "~/components/docs/ComponentExample.astro";
import ComponentSection from "~/components/docs/ComponentSection.astro";
import CodeBlock from "~/components/docs/CodeBlock.astro";
import PropsTable from "~/components/docs/PropsTable.astro";
import {
  CheckboxBasicDemo,
  CheckboxDefaultDemo,
  CheckboxCheckedDemo,
  CheckboxIndeterminateDemo,
  CheckboxLabelFirstDemo,
  CheckboxDisabledDemo,
  CheckboxErrorDemo,
  CheckboxGroupDemo,
  CheckboxGroupErrorDemo,
  CheckboxLegendSrOnlyDemo,
  CheckboxLegendCustomDemo,
} from "~/components/demos/CheckboxDemo";

{/* Hero Demo */}

<ComponentSection>
  <ComponentExample demo="CheckboxBasicDemo">
    <CheckboxBasicDemo client:visible />
  </ComponentExample>
</ComponentSection>

{/* Installation */}

<ComponentSection>

## Installation

### Barrel

<CodeBlock code={`import { Checkbox } from "@cloudflare/kumo";`} lang="tsx" />

### Granular

  <CodeBlock
    code={`import { Checkbox } from "@cloudflare/kumo/components/checkbox";`}
    lang="tsx"
  />
</ComponentSection>

{/* Usage */}

<ComponentSection>

## Usage

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

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

</ComponentSection>

{/* Examples */}

<ComponentSection>

## Examples

### Default

<p>
  Checkbox with built-in label. The label automatically displays in a horizontal
  layout (checkbox before label).
</p>
<ComponentExample demo="CheckboxDefaultDemo">
  <CheckboxDefaultDemo client:visible />
</ComponentExample>

### Checked

<ComponentExample demo="CheckboxCheckedDemo">
  <CheckboxCheckedDemo client:visible />
</ComponentExample>

### Indeterminate

<p>Used for "select all" patterns when some but not all items are selected.</p>
<ComponentExample demo="CheckboxIndeterminateDemo">
  <CheckboxIndeterminateDemo client:visible />
</ComponentExample>

### Label First Layout

<p>Use `controlFirst={false}` to place the label before the checkbox.</p>
<ComponentExample demo="CheckboxLabelFirstDemo">
  <CheckboxLabelFirstDemo client:visible />
</ComponentExample>

### Disabled

<ComponentExample demo="CheckboxDisabledDemo">
  <CheckboxDisabledDemo client:visible />
</ComponentExample>

### Error

<p>
  Error variant provides visual styling (red ring). For error messages, use
  Checkbox.Group.
</p>
<ComponentExample demo="CheckboxErrorDemo">
  <CheckboxErrorDemo client:visible />
</ComponentExample>

### Checkbox Group

<p>
  Group multiple checkboxes with a legend, description, and shared error
  messages. Uses Checkbox.Group and Checkbox.Item.
</p>
<ComponentExample demo="CheckboxGroupDemo">
  <CheckboxGroupDemo client:visible />
</ComponentExample>

### Checkbox Group with Error

<p>
  Show validation errors at the group level. Error replaces description when
  present.
</p>
<ComponentExample demo="CheckboxGroupErrorDemo">
  <CheckboxGroupErrorDemo client:visible />
</ComponentExample>

### Visually Hidden Legend

<p>
  Use `Checkbox.Legend` with `className="sr-only"` to keep the legend accessible
  to screen readers while hiding it visually. This is useful when the group is
  already labeled by a parent `Field` or heading, and showing the legend would
  create a redundant label.
</p>
<ComponentExample demo="CheckboxLegendSrOnlyDemo">
  <CheckboxLegendSrOnlyDemo client:visible />
</ComponentExample>

### Custom Legend Styling

<p>
  `Checkbox.Legend` accepts `className` for full control over legend
  presentation. Use it instead of the `legend` string prop when you need custom
  typography, colors, or layout.
</p>
<ComponentExample demo="CheckboxLegendCustomDemo">
  <CheckboxLegendCustomDemo client:visible />
</ComponentExample>

</ComponentSection>

{/* API Reference */}

<ComponentSection>

## API Reference

### Checkbox

<p>Single checkbox component with built-in label and horizontal layout.</p>
<PropsTable component="Checkbox" />

### Checkbox.Group

<p>
  Wrapper for multiple checkboxes with legend, description, and error support.
</p>
<PropsTable component="Checkbox.Group" />

### Checkbox.Legend

<p>
  Composable legend sub-component for Checkbox.Group. Accepts `className` for
  full styling control (e.g. `className="sr-only"` to visually hide). Use
  instead of the `legend` string prop when you need custom legend styling.
</p>
<PropsTable component="Checkbox.Legend" />

### Checkbox.Item

  <p>Individual checkbox within Checkbox.Group.</p>
  <PropsTable component="Checkbox.Item" />
</ComponentSection>

{/* Accessibility */}

<ComponentSection>

## Accessibility

  <div class="space-y-4 text-sm">
    <div>

      ### Label Requirement

      <p>
        Single checkboxes require a `label` prop or `aria-label` for accessibility.
        Missing labels trigger console warnings in development.
      </p>
    </div>
    <div>

      ### Keyboard Navigation

      <p>
        <kbd class="rounded bg-kumo-control px-1.5 py-0.5">Space</kbd> toggles
        the checkbox.
        <kbd class="rounded bg-kumo-control px-1.5 py-0.5">Tab</kbd> moves focus
        between checkboxes.
      </p>
    </div>
    <div>

      ### Screen Readers

      <p>
        Checkbox.Group uses semantic `<fieldset>` and `<legend>` elements for
        proper grouping announcement.
      </p>
    </div>

  </div>
</ComponentSection>
