---
title: "Checkbox"
description: "A binary state with partial-selection support. The label and description stay separate from the accessible name."
kind: component
id: C-011
registry: "checkbox"
docs: "https://koten.codehive.com.co/components/checkbox"
markdown: "https://koten.codehive.com.co/md/components/checkbox.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/checkbox.json"
language: en
---

# Checkbox · チェック

> Component C-011 in the Koten UI catalog.

A binary state with partial-selection support. The label and description stay separate from the accessible name.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/checkbox.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/checkbox.json
```

## Files

- `@/components/ui/checkbox.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Reference

- Upstream primitive: https://base-ui.com/react/components/checkbox

## Examples

### States

Checked, partial and disabled; the description renders under the label, outside the accessible name.

```tsx
<Checkbox label="Stock alerts" description="Only critical products." defaultChecked />
<Checkbox
  label="Partial selection"
  description="Some rows in this group are selected."
  indeterminate
/>
<Checkbox label="Email digest" description="This channel is not available." disabled />
```

### Controlled state

checked and onCheckedChange keep the state in the consuming component.

```tsx
const [alerts, setAlerts] = useState(true);
const [digest, setDigest] = useState(false);

<Checkbox
  label="Stock alerts"
  description="Only critical products."
  checked={alerts}
  onCheckedChange={setAlerts}
/>
<Checkbox
  label="Order digest"
  description="A summary every morning at 09:00."
  checked={digest}
  onCheckedChange={setDigest}
/>
<p className="text-2xs text-muted">
  Active channels: <span className="font-semibold text-ink">{Number(alerts) + Number(digest)}</span>
</p>
```

### Use inside a form

The required checkbox shares the form with its description and an error that says what is missing before continuing.

```tsx
<form
  className="grid w-full max-w-sm gap-[var(--koten-gap)]"
  onSubmit={(event) => event.preventDefault()}
>
  <div className="grid gap-1">
    <Checkbox
      label="I accept the return policy"
      description="Returns are accepted within 30 days of delivery."
    />
    <p role="alert" className="text-2xs leading-relaxed text-danger">
      You must accept the policy to continue.
    </p>
  </div>
  <div className="flex justify-end">
    <Button type="submit" variant="primary">Continue</Button>
  </div>
</form>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | `ReactNode` | `—` | Visible content and accessible name; required. |
| `description` | `ReactNode` | `—` | Renders under the label, outside the accessible name. |
| `checked / defaultChecked` | `boolean` | `false` | Controlled or uncontrolled. |
| `indeterminate` | `boolean` | `false` | Shows a dash and is announced as mixed; it does not change checked. |
| `onCheckedChange` | `(checked: boolean, event: Event) => void` | `—` | Fires when the box is checked or unchecked. |
| `disabled` | `boolean` | `false` | Blocks the control and excludes it from submission. |
| `name` | `string` | `—` | Name the value travels with in the form. |

## Accessibility

- The label wraps Base UI's real control, so the accessible name comes from the visible text.
- description renders outside the label so the accessible name stays short.
- indeterminate is announced as mixed and does not replace checked.
- Visible focus uses a 2 px outline with an offset, never outline: none.

## Sources

- Catalog page: https://koten.codehive.com.co/components/checkbox
- Markdown: https://koten.codehive.com.co/md/components/checkbox.md
- Repository: https://github.com/codehive-colombia/koten