# 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.
```ts title="basic.ts"
import "@ui-sdk/web/checkbox"
import { Check, createElement } from "lucide"
function mount(root: HTMLElement) {
root.innerHTML = `
`
}
export { mount }
```
Click the checkbox or its label, or focus it and press Space, to accept the terms.
## Installation
```bash
npm install @ui-sdk/web @ui-sdk/core
```
Import the component to register its elements. The import is safe on the server.
```ts
import "@ui-sdk/web/checkbox"
```
## Composition
Use the following composition to build a `ui-checkbox`:
```text
ui-checkbox
└── ui-checkbox-indicator
```
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:
```html
```
## Description
Use `ui-field-label` and `ui-field-description` when a choice needs more explanation. The field connects both to the checkbox.
```ts title="description.ts"
import "@ui-sdk/web/checkbox"
import "@ui-sdk/web/field"
import { Check, createElement } from "lucide"
function mount(root: HTMLElement) {
root.innerHTML = `
${createElement(Check, { "aria-hidden": "true" }).outerHTML}
Accept terms and conditions
By clicking this checkbox, you agree to the terms and conditions.
`
}
export { mount }
```
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.
```ts title="disabled.ts"
import "@ui-sdk/web/checkbox"
import { Check, createElement } from "lucide"
function mount(root: HTMLElement) {
root.innerHTML = `
`
}
export { mount }
```
Security alerts are always on, so that checkbox is disabled. Clicking its label leaves it checked.
## Read-Only
`read-only` keeps the checkbox focusable and included in form submissions, while preventing the user from changing it.
```ts title="read-only.ts"
import "@ui-sdk/web/checkbox"
import "@ui-sdk/web/field"
import { Check, createElement } from "lucide"
function mount(root: HTMLElement) {
root.innerHTML = `
${createElement(Check, { "aria-hidden": "true" }).outerHTML}
Require two-factor authentication
Your organization requires this setting.
`
}
export { mount }
```
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 `default-checked="indeterminate"`, or pass `"indeterminate"` as the controlled value. The indicator's `data-indeterminate` tells it which icon to show. A [parent checkbox](#parent-checkbox) derives this state from a group for you.
```html
–
```
## Controlled
Read or set the element's `checked` property and listen for `checkedchange`. Its `api` property is a [controller](#checkbox-controller) that changes it from anywhere, like the Toggle button below.
```ts title="controlled.ts"
import "@ui-sdk/web/checkbox"
import { Check, createElement } from "lucide"
import { log } from "./log"
function mount(root: HTMLElement) {
root.innerHTML = `
`
const updates = root.querySelector("ui-checkbox")!
root
.querySelector("[data-slot=controls] button")!
.addEventListener("click", () => updates.api.toggle())
updates.addEventListener("checkedchange", (event) => {
const { value, reason } = event.detail
log(
root,
`${value === "indeterminate" ? "Mixed" : value ? "Checked" : "Unchecked"} (${reason})`
)
})
}
export { mount }
```
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 `default-checked`. Set `form` to a form's id to join it from elsewhere on the page.
```ts title="form.ts"
import "@ui-sdk/web/checkbox"
import "@ui-sdk/web/field"
import { Check, createElement } from "lucide"
import { log } from "./log"
function mount(root: HTMLElement) {
root.innerHTML = `
`
const form = root.querySelector("form")!
form.addEventListener("submit", (event) => {
event.preventDefault()
const entries = [...new FormData(form)].map(
([name, value]) => `${name}=${value}`
)
log(
root,
entries.length ? `Submitted ${entries.join("&")}` : "Submitted nothing"
)
})
}
export { mount }
```
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
`ui-checkbox-group` 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).
```ts title="group.ts"
import "@ui-sdk/web/checkbox"
import { Check, createElement } from "lucide"
const toppings = [
{ value: "cheese", label: "Cheese" },
{ value: "mushrooms", label: "Mushrooms" },
{ value: "olives", label: "Olives" },
{ value: "peppers", label: "Peppers" },
]
function mount(root: HTMLElement) {
root.innerHTML = `
Toppings
${toppings
.map(
(topping) => `
`
)
.join("")}
`
}
export { mount }
```
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 `all-values` 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.
```ts title="group-parent.ts"
import "@ui-sdk/web/checkbox"
import { Check, createElement, Minus } from "lucide"
const toppings = [
{ value: "cheese", label: "Cheese" },
{ value: "mushrooms", label: "Mushrooms" },
{ value: "olives", label: "Olives" },
{ value: "peppers", label: "Peppers" },
]
function mount(root: HTMLElement) {
root.innerHTML = `
Toppings
${toppings
.map(
(topping) => `
`
)
.join("")}
`
}
export { mount }
```
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.
```ts title="group-disabled.ts"
import "@ui-sdk/web/checkbox"
import { Check, createElement, Minus } from "lucide"
const backups = [
{ value: "photos", label: "Photos" },
{ value: "documents", label: "Documents" },
{ value: "messages", label: "Messages" },
]
const folders = [
{ value: "desktop", label: "Desktop", disabled: true },
{ value: "projects", label: "Projects", disabled: false },
{ value: "downloads", label: "Downloads", disabled: false },
]
function mount(root: HTMLElement) {
root.innerHTML = `
Backups
Managed by your organization.
${backups
.map(
(item) => `
`
)
.join("")}
Sync folders
${folders
.map(
(item) => `
`
)
.join("")}
`
}
export { mount }
```
The Backups group is disabled. In Sync folders, Select all changes the enabled folders while Desktop stays checked.
## Controlled Group
Read or set the group element's `value` property and listen for `valuechange`. Its `api` property is a [controller](#checkboxgroup-controller) that can replace that list, as Select Weekdays and Clear do below.
```ts title="group-controlled.ts"
import "@ui-sdk/web/checkbox"
import { Check, createElement } from "lucide"
import { log } from "./log"
const days = [
{ value: "mon", label: "Monday" },
{ value: "tue", label: "Tuesday" },
{ value: "wed", label: "Wednesday" },
{ value: "thu", label: "Thursday" },
{ value: "fri", label: "Friday" },
{ value: "sat", label: "Saturday" },
{ value: "sun", label: "Sunday" },
]
const weekdays = ["mon", "tue", "wed", "thu", "fri"]
function mount(root: HTMLElement) {
root.innerHTML = `
Working days
${days
.map(
(day) => `
`
)
.join("")}
`
const schedule = root.querySelector("ui-checkbox-group")!
root
.querySelector('[data-action="weekdays"]')!
.addEventListener("click", () => schedule.api.setValue(weekdays))
root
.querySelector('[data-action="clear"]')!
.addEventListener("click", () => schedule.api.setValue([]))
schedule.addEventListener("valuechange", (event) => {
const { value, reason } = event.detail
const names = days
.filter((day) => value.includes(day.value))
.map((day) => day.label)
log(root, `${names.join(", ") || "No days"} (${reason})`)
})
}
export { mount }
```
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 `default-value`. 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 `ui-field-error` shows the validation message inline until a selection makes the group valid. [Forms and Validation](/docs/web-components/forms) covers the shared field behavior.
```ts title="group-field.ts"
import "@ui-sdk/web/checkbox"
import "@ui-sdk/web/field"
import { Check, createElement } from "lucide"
import { log } from "./log"
const channels = [
{ value: "email", label: "Email" },
{ value: "sms", label: "SMS" },
{ value: "push", label: "Push notifications" },
]
function mount(root: HTMLElement) {
root.innerHTML = `
`
const form = root.querySelector("form")!
form.addEventListener("submit", (event) => {
event.preventDefault()
const entries = [...new FormData(form)].map(
([name, value]) => `${name}=${value}`
)
log(root, `Saved ${entries.join("&")}`)
})
}
export { mount }
```
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.
```ts title="table.ts"
import "@ui-sdk/web/checkbox"
import { Check, createElement, Minus } from "lucide"
import { log } from "./log"
const people = [
{
id: "hollis",
name: "Hollis Grant",
email: "hollis@example.com",
role: "Owner",
},
{
id: "ines",
name: "Inès Moreau",
email: "ines@example.com",
role: "Editor",
},
{
id: "kofi",
name: "Kofi Mensah",
email: "kofi@example.com",
role: "Viewer",
},
{
id: "wren",
name: "Wren Takahashi",
email: "wren@example.com",
role: "Editor",
},
]
function mount(root: HTMLElement) {
root.innerHTML = `
`
root
.querySelector("ui-checkbox-group")!
.addEventListener("valuechange", (event) => {
log(root, `${event.detail.value.length} of ${people.length} selected`)
})
}
export { mount }
```
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;
}
}
```
`keep-mounted` keeps the indicator in the page while unchecked, with `data-unchecked`, for styles that show both states.
```ts title="indicator.ts"
import "@ui-sdk/web/checkbox"
import { Check, createElement } from "lucide"
const tasks = [
{ label: "Write the release notes", done: false },
{ label: "Update the changelog", done: true },
{ label: "Tag the release", done: false },
]
function mount(root: HTMLElement) {
root.innerHTML = `
${tasks
.map(
(task) => `
`
)
.join("")}
`
}
export { mount }
```
Check and uncheck a task. The check scales and fades in, and out before it unmounts.
## Custom Rendering
Elements have no render functions. `ui-checkbox` is the interactive element itself, so put your content inside it, where its role, label, and keyboard behavior stay connected. Style it from its attributes, and watch them to change what's inside: here each checkbox swaps its icon when `data-checked` changes.
```ts title="render.ts"
import "@ui-sdk/web/checkbox"
import { Check, createElement, Plus } from "lucide"
const topics = [
{ value: "design", label: "Design", checked: true },
{ value: "engineering", label: "Engineering", checked: false },
{ value: "marketing", label: "Marketing", checked: false },
{ value: "sales", label: "Sales", checked: false },
]
const icon = (checked: boolean) =>
createElement(checked ? Check : Plus, { "aria-hidden": "true" }).outerHTML
function mount(root: HTMLElement) {
root.innerHTML = `
`
const update = (checkbox: Element) => {
checkbox.querySelector("svg")!.outerHTML = icon(
checkbox.hasAttribute("data-checked")
)
}
new MutationObserver((records) =>
records.forEach((record) => update(record.target as Element))
).observe(root, { subtree: true, attributeFilter: ["data-checked"] })
root.querySelectorAll("ui-checkbox").forEach(update)
}
export { mount }
```
Choose topics. Each checkbox 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
### ``
`[data-slot="checkbox"]`
- `data-checked`: Present while checked.
- `data-disabled`: Present when disabled, by its own prop, a group or a `