Search docs

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>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/checkbox

Anatomy#

import { Checkbox } from '@leve-ui/checkbox'; // or '@leve-ui/core'

<Checkbox.Root>
  <Checkbox.Control>
    <Checkbox.Indicator />
  </Checkbox.Control>
  <Checkbox.Label />
  <Checkbox.HiddenInput />
</Checkbox.Root>
PartElementDescription
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.

Disabled#

disabled on the Root disables the checkbox.

Indeterminate#

The checked state can be "indeterminate", for example for a "select all" checkbox. This demo controls the states with bind:checked and onCheckedChange$.

(1 of 3 selected)

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.

Save your session on this device for 30 days.

With Form#

Add Checkbox.HiddenInput with name and value to submit the state with a native <form>.

API Reference#

Root#

PropDefaultType
ids–{ control?: string; label?: string }

Overrides the element IDs of the parts. Only used outside a Field.

defaultCheckedfalseboolean | '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.

disabledfalseboolean

Disables the checkbox. Inside a Field, the Field's disabled also applies.

requiredfalseboolean

Marks the checkbox as required. Inside a Field, the Field's required also applies.

Also accepts all <div> attributes.

Data attributeValue
data-leve-checkboxAlways present
data-state"checked" | "unchecked" | "indeterminate"
data-disabledPresent 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 attributeValue
data-leve-checkbox-controlAlways present
data-state"checked" | "unchecked" | "indeterminate"
data-disabledPresent when disabled
data-invalidPresent when the Field is invalid

Indicator#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-checkbox-indicatorAlways present
data-state"checked" | "unchecked" | "indeterminate"
data-disabledPresent 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 attributeValue
data-leve-checkbox-labelAlways present
data-state"checked" | "unchecked" | "indeterminate"
data-disabledPresent when disabled

HiddenInput#

No props of its own. Accepts all <input> attributes.

Data attributeValue
data-leve-checkbox-hidden-inputAlways present
data-state"checked" | "unchecked" | "indeterminate"
data-disabledPresent 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, or aria-label / aria-labelledby on Checkbox.Control.
  • Checkbox.Control renders role="checkbox" and aria-checked ("true", "false" or "mixed"), and aria-required when required. Inside a Field it also renders aria-describedby and aria-invalid.
  • Do not change the label text with the state. The state is conveyed by aria-checked.
  • Checkbox.Indicator and Checkbox.HiddenInput are hidden from assistive technologies with aria-hidden="true".

Keyboard Interactions#

KeyDescription
SpaceChecks or unchecks the checkbox.
EnterChecks or unchecks the checkbox.