# Checkbox
Choose one or more options, individually or as a group.
Use a checkbox for a choice someone can check or uncheck. Use a group when several choices belong to one value.
```svelte title="basic.svelte"
```
Click the checkbox or its label, or focus it and press Space, to accept the terms.
## Installation
```bash
npm install @ui-sdk/svelte @ui-sdk/core
```
## Composition
Use the following composition to build a `Checkbox`:
```text
Checkbox
└── CheckboxIndicator
```
Wrap the checkbox and its text in a label. The indicator shows while the checkbox is checked or mixed.
## Usage
Import the parts and put them together:
```svelte
```
## Description
Use `FieldLabel` and `FieldDescription` when a choice needs more explanation. The field connects both to the checkbox.
```svelte title="description.svelte"
Accept terms and conditions
By clicking this checkbox, you agree to the terms and conditions.
```
Click Accept terms and conditions. The field connects the label and description to the checkbox.
## Disabled
`disabled` prevents focus and changes, and leaves the checkbox out of form submissions. A disabled `fieldset` does the same.
```svelte title="disabled.svelte"
```
Security alerts are always on, so that checkbox is disabled. Clicking its label leaves it checked.
## Read-Only
`readOnly` keeps the checkbox focusable and included in form submissions, while preventing the user from changing it.
```svelte title="read-only.svelte"
Require two-factor authentication
Your organization requires this setting.
```
Tab to the checked checkbox. Space and clicks leave the setting unchanged.
## Indeterminate
An indeterminate checkbox represents a partly checked set. It has `aria-checked="mixed"` and `data-indeterminate`. A press checks it; only your code puts it back into the mixed state.
Start with `defaultChecked="indeterminate"`, or pass `"indeterminate"` as the controlled value. The indicator's state tells it which icon to show. A [parent checkbox](#parent-checkbox) derives this state from a group for you.
```svelte
{#snippet children(state)}
{#if state.indeterminate}{:else}{/if}
{/snippet}
```
## Controlled
Use `bind:checked` to own the value. A [controller](#checkbox-controller) from `createCheckboxController()` changes it from anywhere, like the Toggle button below.
```svelte title="controlled.svelte"
```
Change the checkbox, or press Toggle. The console logs each change and its reason.
## Forms
Set `name` and `value` to include a checked checkbox in a native form. Unchecked and mixed checkboxes submit nothing. The default value is `"on"`. Independent checkboxes can share a name to submit several values; use a [group](#group) when your app also needs one list of checked values.
`required` blocks submission until the checkbox is checked. Reset returns it to `defaultChecked`. Set `form` to a form's id to join it from elsewhere on the page.
```svelte title="form.svelte"
```
Create the account with the terms unchecked to see native validation, then accept them and try again. The console logs what was submitted, and Reset restores the defaults.
## Group
`CheckboxGroup` keeps one list of checked values. Each checkbox supplies its `value`; the group returns selected values in the order the checkboxes appear. Name the group with `aria-label`, `aria-labelledby`, or a [Field](#group-in-a-form).
```svelte title="group.svelte"
Toppings
{#each toppings as topping (topping.value)}
{/each}
```
Choose several toppings. The group keeps one list of checked values.
## Parent Checkbox
Add a checkbox with `parent` to check or uncheck the group. It is checked when every value is selected, unchecked when none are, and mixed in between. It points to its children with `aria-controls` and submits nothing itself.
Pass `allValues` to the group so the parent has the right state on the first render, including on the server. Otherwise it discovers the values after the checkboxes mount.
```svelte title="group-parent.svelte"
Toppings
topping.value)}
>
{#each toppings as topping (topping.value)}
{/each}
```
Select all checks every topping. Uncheck one topping to put Select all into its mixed state.
## Disabled Group
Disable the group to lock every checkbox, or disable one child to keep just that value fixed. A parent changes only enabled children.
```svelte title="group-disabled.svelte"
Backups
Managed by your organization.
{#each backups as item (item.value)}
{/each}
Sync folders
item.value)}
>
{#each folders as item (item.value)}
{/each}
```
The Backups group is disabled. In Sync folders, Select all changes the enabled folders while Desktop stays checked.
## Controlled Group
Use `bind:value` to own the selected values. A [controller](#checkboxgroup-controller) can replace that list, as Select Weekdays and Clear do below.
```svelte title="group-controlled.svelte"
Working days
{
const names = days
.filter((day) => next.includes(day.value))
.map((day) => day.label)
log(`${names.join(", ") || "No days"} (${details.reason})`)
}}
>
{#each days as day (day.value)}
{/each}
```
Choose working days, or press Select Weekdays or Clear. The console logs the group's value and the reason it changed.
## Group in a Form
Set `name` on the group to submit every checked value under that name. `required` requires at least one selection, and Reset restores `defaultValue`. The same `disabled` and `form` options apply as on a single checkbox.
In a field, the field supplies the group's label and description, and `FieldError` shows the validation message inline until a selection makes the group valid. [Forms and Validation](/docs/svelte/forms) covers the shared field behavior.
```svelte title="group-field.svelte"
```
Save with nothing checked to see the inline error. Choose a notification method and save; the console logs the submitted values.
## Table
The same parent checkbox can select rows from a table header. Each row supplies its value and accessible name.
```svelte title="table.svelte"
log(`${next.length} of ${people.length} selected`)}
allValues={people.map((person) => person.id)}
>
Team members
Name
Email
Role
{#each people as person (person.id)}
{person.name}
{person.email}
{person.role}
{/each}
```
Select rows individually, or use Select all in the header. The console logs how many are selected.
## Animation
The indicator has `data-starting-style` as it appears and `data-ending-style` while it leaves, and stays mounted until its exit finishes. Transition from those states:
```css
[data-slot="checkbox-indicator"] {
transition:
opacity 0.15s,
scale 0.15s;
&:is([data-starting-style], [data-ending-style]) {
opacity: 0;
scale: 0.5;
}
}
```
`keepMounted` keeps the indicator in the page while unchecked, with `data-unchecked`, for styles that show both states.
```svelte title="indicator.svelte"
{#each tasks as task (task.label)}
{/each}
```
Check and uncheck a task. The check scales and fades in, and out before it unmounts.
## Custom Rendering
The checkbox, indicator, and group take a `render` snippet, which receives the props to spread and the part's state. Keep the part's props on the interactive element so its role, label, and keyboard behavior stay connected.
```svelte title="render.svelte"
```
Choose topics. Each checkbox renders a button that shows a check or a plus from its state.
## Styling
Use `data-checked`, `data-unchecked` and `data-indeterminate` for the checked state, and `data-disabled`, `data-readonly` and `data-required` for the rest. The indicator gets the same state attributes as its checkbox.
Each part has a `data-slot`, such as `checkbox`, and its state attributes are listed under [Data Attributes](#data-attributes).
## Data Attributes
### Checkbox
`[data-slot="checkbox"]`
- `data-checked`: Present while checked.
- `data-disabled`: Present when disabled, by its own prop, a group or a `