Checkbox
A control that is checked, unchecked, or mixed.
Checkbox follows the Checkbox WAI-ARIA design pattern.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@leve-ui/checkbox';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './default.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Checkbox.Root class="checkbox-default-root">
<Checkbox.Control class="checkbox-default-control">
<Checkbox.Indicator class="checkbox-default-indicator">
<LuCheck class="checkbox-default-icon" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-default-label">Accept terms and conditions</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
);
});.checkbox-default-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
font-family: inherit;
}
.checkbox-default-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-default-control[data-state="checked"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-default-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-default-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* The indicator is always rendered; show it only when checked */
.checkbox-default-indicator {
display: none;
color: #ffffff;
}
.checkbox-default-indicator[data-state="checked"] {
display: inline-flex;
}
.checkbox-default-icon {
width: 12px;
height: 12px;
}
.checkbox-default-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
pnpm add @leve-ui/checkboxnpm install @leve-ui/checkboxyarn add @leve-ui/checkboxbun add @leve-ui/checkboxpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/coreAnatomy#
import { Checkbox } from '@leve-ui/checkbox'; // or '@leve-ui/core'
<Checkbox.Root>
<Checkbox.Control>
<Checkbox.Indicator />
</Checkbox.Control>
<Checkbox.Label />
<Checkbox.HiddenInput />
</Checkbox.Root>
| Part | Element | Description |
|---|---|---|
Checkbox.Root | <div> | Wraps the parts and holds the checked state. Not interactive. |
Checkbox.Control | <button> | The checkbox itself, with role="checkbox". |
Checkbox.Indicator | <span> | Holds the check mark or other icons. Always rendered. |
Checkbox.Label | <label> | The label. Clicking it toggles the checkbox. |
Checkbox.HiddenInput | <input type="checkbox"> | Optional. Sends the state with a native <form>. |
Examples#
Checked#
defaultChecked sets the initial state.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@leve-ui/checkbox';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './checked.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Checkbox.Root defaultChecked={true} class="checkbox-checked-root">
<Checkbox.Control class="checkbox-checked-control">
<Checkbox.Indicator class="checkbox-checked-indicator">
<LuCheck class="checkbox-checked-icon" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-checked-label">Subscribe to newsletter</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
);
});.checkbox-checked-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
font-family: inherit;
}
.checkbox-checked-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-checked-control[data-state="checked"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-checked-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-checked-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* The indicator is always rendered; show it only when checked */
.checkbox-checked-indicator {
display: none;
color: #ffffff;
}
.checkbox-checked-indicator[data-state="checked"] {
display: inline-flex;
}
.checkbox-checked-icon {
width: 12px;
height: 12px;
}
.checkbox-checked-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}Disabled#
disabled on the Root disables the checkbox.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@leve-ui/checkbox';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './disabled.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Checkbox.Root disabled class="checkbox-disabled-root">
<Checkbox.Control class="checkbox-disabled-control">
<Checkbox.Indicator class="checkbox-disabled-indicator">
<LuCheck class="checkbox-disabled-icon" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-disabled-label">Disabled option</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
);
});.checkbox-disabled-root {
font-family: inherit;
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
}
.checkbox-disabled-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-disabled-control[data-state="checked"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-disabled-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-disabled-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* The indicator is always rendered; show it only when checked */
.checkbox-disabled-indicator {
display: none;
color: #ffffff;
}
.checkbox-disabled-indicator[data-state="checked"] {
display: inline-flex;
}
.checkbox-disabled-icon {
width: 12px;
height: 12px;
}
.checkbox-disabled-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.checkbox-disabled-label[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}Indeterminate#
The checked state can be "indeterminate", for example for a "select all" checkbox. This demo controls the states with bind:checked and onCheckedChange$.
import { $, component$, useComputed$, useSignal, useStyles$, useTask$ } from '@builder.io/qwik';
import { Checkbox, type CheckboxCheckedState } from '@leve-ui/checkbox';
import { LuCheck, LuMinus } from '@qwikest/icons/lucide';
import styles from './indeterminate.css?inline';
export default component$(() => {
useStyles$(styles);
const child1 = useSignal(true);
const child2 = useSignal(false);
const child3 = useSignal(false);
const parent = useSignal<CheckboxCheckedState>('indeterminate');
// Synchronize parent state based on child values
useTask$(({ track }) => {
const c1 = track(() => child1.value);
const c2 = track(() => child2.value);
const c3 = track(() => child3.value);
const all = c1 && c2 && c3;
const none = !c1 && !c2 && !c3;
if (all) {
parent.value = true;
} else if (none) {
parent.value = false;
} else {
parent.value = 'indeterminate';
}
});
const selectedCount = useComputed$(() => {
return [child1.value, child2.value, child3.value].filter(Boolean).length;
});
const handleParentChange$ = $((next: CheckboxCheckedState) => {
const target = next === true;
child1.value = target;
child2.value = target;
child3.value = target;
});
return (
<div class="checkbox-indeterminate-group">
<Checkbox.Root
bind:checked={parent}
onCheckedChange$={handleParentChange$}
class="checkbox-indeterminate-root"
>
<Checkbox.Control class="checkbox-indeterminate-control">
<Checkbox.Indicator class="checkbox-indeterminate-indicator">
<LuCheck class="checkbox-indeterminate-icon-check" aria-hidden="true" />
<LuMinus class="checkbox-indeterminate-icon-indeterminate" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-indeterminate-label">Select all ingredients</Checkbox.Label>
<span class="checkbox-indeterminate-count">({selectedCount.value} of 3 selected)</span>
<Checkbox.HiddenInput />
</Checkbox.Root>
<div class="checkbox-indeterminate-group-children">
<Checkbox.Root bind:checked={child1} class="checkbox-indeterminate-root">
<Checkbox.Control class="checkbox-indeterminate-control">
<Checkbox.Indicator class="checkbox-indeterminate-indicator">
<LuCheck class="checkbox-indeterminate-icon-check" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-indeterminate-label">Lettuce</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
<Checkbox.Root bind:checked={child2} class="checkbox-indeterminate-root">
<Checkbox.Control class="checkbox-indeterminate-control">
<Checkbox.Indicator class="checkbox-indeterminate-indicator">
<LuCheck class="checkbox-indeterminate-icon-check" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-indeterminate-label">Tomato</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
<Checkbox.Root bind:checked={child3} class="checkbox-indeterminate-root">
<Checkbox.Control class="checkbox-indeterminate-control">
<Checkbox.Indicator class="checkbox-indeterminate-indicator">
<LuCheck class="checkbox-indeterminate-icon-check" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-indeterminate-label">Cheese</Checkbox.Label>
<Checkbox.HiddenInput />
</Checkbox.Root>
</div>
</div>
);
});.checkbox-indeterminate-group {
display: flex;
flex-direction: column;
gap: 12px;
font-family: inherit;
}
.checkbox-indeterminate-group-children {
display: flex;
flex-direction: column;
gap: 12px;
padding-left: 28px;
}
.checkbox-indeterminate-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
}
.checkbox-indeterminate-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-indeterminate-control[data-state="checked"],
.checkbox-indeterminate-control[data-state="indeterminate"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-indeterminate-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* The indicator is always rendered; show it only when checked or indeterminate */
.checkbox-indeterminate-indicator {
display: none;
color: #ffffff;
}
.checkbox-indeterminate-indicator[data-state="checked"],
.checkbox-indeterminate-indicator[data-state="indeterminate"] {
display: inline-flex;
}
.checkbox-indeterminate-icon-check,
.checkbox-indeterminate-icon-indeterminate {
display: none;
width: 12px;
height: 12px;
}
/* Check icon when checked, minus icon when indeterminate */
.checkbox-indeterminate-indicator[data-state="checked"] .checkbox-indeterminate-icon-check,
.checkbox-indeterminate-indicator[data-state="indeterminate"]
.checkbox-indeterminate-icon-indeterminate {
display: block;
}
.checkbox-indeterminate-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.checkbox-indeterminate-count {
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}With Field#
Inside a Field.Root, use Field.Label instead of Checkbox.Label. The Field provides the IDs, the description and the disabled / required / invalid states.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@leve-ui/checkbox';
import { Field } from '@leve-ui/field';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './with-field.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Field.Root hasDescription class="checkbox-with-field-field">
<div class="checkbox-with-field-row">
<Checkbox.Root class="checkbox-with-field-root">
<Checkbox.Control class="checkbox-with-field-control">
<Checkbox.Indicator class="checkbox-with-field-indicator">
<LuCheck class="checkbox-with-field-icon" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.HiddenInput />
</Checkbox.Root>
<Field.Label class="checkbox-with-field-label">Remember me</Field.Label>
</div>
<Field.Description class="checkbox-with-field-description">
Save your session on this device for 30 days.
</Field.Description>
</Field.Root>
);
});.checkbox-with-field-field {
display: flex;
flex-direction: column;
gap: 6px;
width: 280px;
font-family: inherit;
}
.checkbox-with-field-row {
display: flex;
align-items: center;
gap: 10px;
}
.checkbox-with-field-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
}
.checkbox-with-field-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-with-field-control[data-state="checked"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-with-field-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-with-field-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* The indicator is always rendered; show it only when checked */
.checkbox-with-field-indicator {
display: none;
color: #ffffff;
}
.checkbox-with-field-indicator[data-state="checked"] {
display: inline-flex;
}
.checkbox-with-field-icon {
width: 12px;
height: 12px;
}
.checkbox-with-field-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
/* Indented to line up with the label text (control 18px + gap 10px) */
.checkbox-with-field-description {
margin: 0;
padding-left: 28px;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}With Form#
Add Checkbox.HiddenInput with name and value to submit the state with a native <form>.
import { $, component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Checkbox } from '@leve-ui/checkbox';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './with-form.css?inline';
export default component$(() => {
useStyles$(styles);
const submittedData = useSignal('');
const handleSubmit$ = $((_event: unknown, form: HTMLFormElement) => {
const formData = new FormData(form);
submittedData.value = JSON.stringify(Object.fromEntries(formData));
});
return (
<form class="checkbox-with-form-form" preventdefault:submit onSubmit$={handleSubmit$}>
<Checkbox.Root class="checkbox-with-form-root">
<Checkbox.Control class="checkbox-with-form-control">
<Checkbox.Indicator class="checkbox-with-form-indicator">
<LuCheck class="checkbox-with-form-icon" aria-hidden="true" />
</Checkbox.Indicator>
</Checkbox.Control>
<Checkbox.Label class="checkbox-with-form-label">Agree to marketing emails</Checkbox.Label>
<Checkbox.HiddenInput name="marketing" value="subscribed" />
</Checkbox.Root>
<button type="submit" class="checkbox-with-form-submit">
Submit
</button>
<output class="checkbox-with-form-output">{submittedData.value}</output>
</form>
);
});.checkbox-with-form-root {
/* HiddenInput is absolutely positioned inside Root */
position: relative;
display: inline-flex;
align-items: center;
gap: 10px;
}
.checkbox-with-form-control {
display: inline-flex;
align-items: center;
justify-content: center;
width: 18px;
height: 18px;
padding: 0;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 4px;
background: light-dark(#ffffff, #1b2045);
cursor: pointer;
}
.checkbox-with-form-control[data-state="checked"] {
background: #009dfd;
border-color: #009dfd;
}
.checkbox-with-form-control:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-with-form-control:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* The indicator is always rendered; show it only when checked */
.checkbox-with-form-indicator {
display: none;
color: #ffffff;
}
.checkbox-with-form-indicator[data-state="checked"] {
display: inline-flex;
}
.checkbox-with-form-icon {
width: 12px;
height: 12px;
}
.checkbox-with-form-label {
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.checkbox-with-form-form {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 12px;
font-family: inherit;
}
.checkbox-with-form-submit {
height: 32px;
padding: 0 12px;
border: none;
border-radius: 6px;
background: #009dfd;
color: #ffffff;
font: inherit;
font-size: 13px;
font-weight: 500;
cursor: pointer;
}
.checkbox-with-form-submit:hover {
background: #006ce9;
}
.checkbox-with-form-submit:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.checkbox-with-form-output {
margin: 0;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}API Reference#
Root#
| Prop | Default | Type |
|---|---|---|
| ids | – | { control?: string; label?: string } Overrides the element IDs of the parts. Only used outside a Field. |
| defaultChecked | false | boolean | 'indeterminate' The initial checked state (uncontrolled). |
| bind:checked | – | Signal<boolean | 'indeterminate'> A signal with the checked state (controlled). |
| onCheckedChange$ | – | QRL<(checked: boolean | 'indeterminate') => void> Called when the user changes the checked state. |
| disabled | false | boolean Disables the checkbox. Inside a Field, the Field's |
| required | false | boolean Marks the checkbox as required. Inside a Field, the Field's |
Also accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-checkbox | Always present |
data-state | "checked" | "unchecked" | "indeterminate" |
data-disabled | Present when disabled |
The checked state is uncontrolled with defaultChecked, or controlled with bind:checked. onCheckedChange$ is called when the user changes it. Toggling an "indeterminate" checkbox makes it checked.
Inside a Field, the IDs come from the Field and ids is ignored (ADR 0024).
Control#
No props of its own. Accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-checkbox-control | Always present |
data-state | "checked" | "unchecked" | "indeterminate" |
data-disabled | Present when disabled |
data-invalid | Present when the Field is invalid |
Indicator#
No props of its own. Accepts all <span> attributes.
| Data attribute | Value |
|---|---|
data-leve-checkbox-indicator | Always present |
data-state | "checked" | "unchecked" | "indeterminate" |
data-disabled | Present when disabled |
The indicator is always rendered. Show or hide its icons with CSS, for example [data-leve-checkbox-indicator][data-state="unchecked"].
Label#
No props of its own. Accepts all <label> attributes.
| Data attribute | Value |
|---|---|
data-leve-checkbox-label | Always present |
data-state | "checked" | "unchecked" | "indeterminate" |
data-disabled | Present when disabled |
HiddenInput#
No props of its own. Accepts all <input> attributes.
| Data attribute | Value |
|---|---|
data-leve-checkbox-hidden-input | Always present |
data-state | "checked" | "unchecked" | "indeterminate" |
data-disabled | Present when disabled |
The hidden input follows the checked, required and disabled states, so native form submission and required validation work (ADR 0026). It is positioned absolutely with an inline style, so give Checkbox.Root position: relative.
Accessibility#
Complies with the Checkbox WAI-ARIA design pattern.
- Name the checkbox with
Checkbox.Label,Field.Label, oraria-label/aria-labelledbyonCheckbox.Control. Checkbox.Controlrendersrole="checkbox"andaria-checked("true","false"or"mixed"), andaria-requiredwhen required. Inside a Field it also rendersaria-describedbyandaria-invalid.- Do not change the label text with the state. The state is conveyed by
aria-checked. Checkbox.IndicatorandCheckbox.HiddenInputare hidden from assistive technologies witharia-hidden="true".
Keyboard Interactions#
| Key | Description |
|---|---|
Space | Checks or unchecks the checkbox. |
Enter | Checks or unchecks the checkbox. |