---
title: "Checkbox"
description: "A binary choice with an optional label and a mixed state."
category: "Form & Input"
slug: checkbox
url: /components/checkbox
since: "0.1.0"
status: "stable"
---

# Checkbox

A binary choice with an optional label and a mixed state.

## Import

```svelte
import { Checkbox } from '@elluzion/iv-ui';
```

## Preview

Unchecked, checked, mixed, and disabled.

```svelte
<script lang="ts">
	import { Checkbox } from '@elluzion/iv-ui';

	let unchecked = $state(false);
	let checked = $state(true);
	let mixed = $state(false);
</script>

<div class="stack">
	<Checkbox label="Unchecked" bind:checked={unchecked} />
	<Checkbox label="Checked" bind:checked />
	<Checkbox label="Mixed" indeterminate bind:checked={mixed} />
	<Checkbox label="Disabled" checked disabled />
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-sm);
	}
</style>
```

## Usage

- Bind `checked` for two-way state; `onchange` receives `{ checked }`.
- Use `indeterminate` for a parent control that represents a partial selection.
- Pass `label` for the visible text; the label is part of the click target.

## Examples

### Sizes

`sm` and `md`; `md` is the default.

```svelte
<script lang="ts">
	import { Checkbox } from '@elluzion/iv-ui';
</script>

<div class="stack">
	<Checkbox label="Small" size="sm" checked />
	<Checkbox label="Medium" checked />
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-sm);
	}
</style>
```

### Events

The change event carries `{ checked }` and the bound value stays in sync.

```svelte
<script lang="ts">
	import { Checkbox } from '@elluzion/iv-ui';

	let checked = $state(false);
	let changes = $state(0);
</script>

<div class="stack">
	<Checkbox label="Watch this repository" bind:checked onchange={() => changes++} />
	<p class="readout">checked {checked} · changes {changes}</p>
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-sm);
	}

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` **bindable** | `boolean` | `false` | Checked state. Bind with `bind:checked`. |
| `indeterminate` | `boolean` | `false` | Renders the mixed state; useful for “select all”. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `required` | `boolean` | `false` | Marks the field as required. |
| `label` | `string` | `''` | Label text rendered next to the box. |
| `name` | `string` | `''` | Form field name submitted with the surrounding form. |
| `value` | `string` | `''` | Value submitted with the form when checked. |
| `size` | `'sm' \| 'md'` | `'md'` | Control size. |

`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `change` | `(e: CustomEvent<{ checked: boolean }>) => void` | Called with `{ checked }` after the state changes. |
| `focus` | `(e: FocusEvent) => void` | Called when the control receives focus. |
| `blur` | `(e: FocusEvent) => void` | Called when the control loses focus. |

The legacy `on:name` form is accepted for every event.

### Snippets

| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |

### Tokens used

`--iv_border` · `--iv_control-md` · `--iv_control-sm` · `--iv_disabled-opacity` · `--iv_ease-out` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-inverse` · `--iv_leading-tight` · `--iv_outline-offset` · `--iv_outline-width` · `--iv_radius-sm` · `--iv_spacing-sm` · `--iv_surface-raised` · `--iv_text-body` · `--iv_transition-fast`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-box` · `.iv-checked` · `.iv-disabled` · `.iv-indeterminate` · `.iv-label` · `.iv-md` · `.iv-native` · `.iv-root` · `.iv-sm`

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the checkbox. |
| `Space` | Toggles the checked state. |

- A native checkbox input backs the control, so form submission works without extra wiring.
- `indeterminate` is applied to the native input and announced as mixed.
- Focus is drawn on the box and is never removed.

## Related

- [Switch](/components/switch.md)
- [RadioGroup](/components/radio-group.md)
- [Toggle](/components/toggle.md)
- [Field](/components/field.md)