---
title: Checkbox
description: >-
  A checkbox control for binary or mixed selection states, with controlled and
  uncontrolled usage.
---

# Checkbox

## Overview

Checkboxes let users turn an option on or off. Use them in contexts where users review selections before applying them in a separate confirmation step.

```tsx
<Field label="Accept terms">
	<Checkbox defaultChecked />
</Field>
```

## Usage Guidelines

- **Use for independent selection:** Use a checkbox when each option can be turned on or off on its own and changes are applied after a separate confirmation step. They work best for settings or lists where users may select any number of items at once.
- **Write clear labels:** Pair each checkbox with a concise label that makes the checked state easy to understand, such as "Send me product updates" or "I agree to the terms." Avoid vague labels that depend on surrounding context to interpret.
- **Use indeterminate status for partial selection:** Use the indeterminate state to show that a parent option reflects a mix of checked and unchecked child items. It should communicate partial selection only, not act as a third selectable value.

## API Reference

### `Checkbox`

| Prop              | Type                         | Default     |
| ----------------- | ---------------------------- | ----------- |
| `checked`         | `boolean`                    | `undefined` |
| `defaultChecked`  | `boolean`                    | `undefined` |
| `onCheckedChange` | `(checked: boolean) => void` | `undefined` |
| `indeterminate`   | `boolean`                    | `false`     |
| `disabled`        | `boolean`                    | `false`     |
| `required`        | `boolean`                    | `false`     |
| `name`            | `string`                     | `undefined` |
| `value`           | `string`                     | `undefined` |

## Examples

### Independent selection

Use checkboxes in lists where each option can be selected on its own. Each item should remain understandable when read independently.

```tsx
<Field label="Email updates" description="Product news and release notes">
	<Checkbox defaultChecked />
</Field>
<Field label="Security alerts" description="Critical account and sign-in notifications">
	<Checkbox defaultChecked />
</Field>
<Field label="Research invites" description="Occasional opportunities to join user interviews">
	<Checkbox />
</Field>
```

### States

Show state changes when they affect validation, availability, or the user's confidence in what will happen after submission.

```tsx
<Field label="Email me a receipt">
	<Checkbox />
</Field>
<Field label="Save payment method">
	<Checkbox defaultChecked />
</Field>
<Field disabled label="Auto-renew subscription" description="Requires administrator approval">
	<Checkbox checked />
</Field>
```

### Indeterminate status

Use the indeterminate state to show that a parent option reflects a mix of checked and unchecked child items. This should be used as status feedback only, not as a third selectable value.

```tsx
const [permissions, setPermissions] = useState({
	dashboards: true,
	reports: false,
	billing: true,
});

const values = Object.values(permissions);
const allChecked = values.every(Boolean);
const someChecked = values.some(Boolean);

<Field label="Quarterly finance report">
	<Checkbox
		checked={allChecked}
		indeterminate={someChecked && !allChecked}
		onCheckedChange={(checked) =>
			setPermissions({
				dashboards: checked,
				reports: checked,
				billing: checked,
			})
		}
	/>
</Field>
<Field label="Executive summary">
	<Checkbox
		checked={permissions.dashboards}
		onCheckedChange={(checked) => setPermissions((current) => ({ ...current, dashboards: checked }))}
	/>
</Field>
<Field label="Revenue breakdown">
	<Checkbox
		checked={permissions.reports}
		onCheckedChange={(checked) => setPermissions((current) => ({ ...current, reports: checked }))}
	/>
</Field>
<Field label="Regional performance appendix">
	<Checkbox
		checked={permissions.billing}
		onCheckedChange={(checked) => setPermissions((current) => ({ ...current, billing: checked }))}
	/>
</Field>
```