Checkbox

A checkbox on a <span role=checkbox> with a hidden native input beside it for forms.

Installation

npx nuecrea-ui add checkbox

Usage

import * as Checkbox from '@/components/ui/checkbox';
import * as Field from '@/components/ui/field';

const label = 'flex items-center gap-2 text-sm';

export default function CheckboxStory() {
  return (
    <main className="grid max-w-sm gap-4">
      <label className={label}>
        <Checkbox.Root>
          <Checkbox.Indicator />
        </Checkbox.Root>
        Email me product updates
      </label>
      <label className={label}>
        <Checkbox.Root defaultChecked>
          <Checkbox.Indicator />
        </Checkbox.Root>
        Remember this device
      </label>
      <label className={label}>
        <Checkbox.Root indeterminate>
          <Checkbox.Indicator />
        </Checkbox.Root>
        Select all
      </label>
      <label className={label}>
        <Checkbox.Root disabled readOnly defaultChecked>
          <Checkbox.Indicator />
        </Checkbox.Root>
        Managed by your admin
      </label>
      <Field.Root validationMode="onChange">
        <Field.Label className={label}>
          <Checkbox.Root name="terms" required>
            <Checkbox.Indicator />
          </Checkbox.Root>
          Accept the terms
        </Field.Label>
        <Field.Error match="valueMissing">You must accept the terms.</Field.Error>
      </Field.Root>
    </main>
  );
}

API reference

Checkbox.Root

The checkbox. Labelled by a wrapping <label> or a Field.Label. Renders <span> with role checkbox.

Prop	Type	Default	Description
`checked`	`boolean`	—	Controlled checked state.
`defaultChecked`	`boolean`	`false`	Initial checked state when uncontrolled.
`indeterminate`	`boolean`	`false`	Mixed state (aria-checked=mixed). Controlled by you; clicking still toggles `checked`.
`name`	`string`	—	Name of the hidden input for form submission.
`value`	`string`	—	Value of the hidden input when checked.
`disabled`	`boolean`	`false`	Ignores interaction and is removed from the tab order.
`readOnly`	`boolean`	`false`	Focusable but cannot be toggled.
`required`	`boolean`	`false`	Must be checked for the form/field to be valid (valueMissing).

Event	Payload	Description
`onCheckedChange`	`boolean`	Fired when the user toggles the checkbox. Angular: the `checked` model's change event.

Data attribute	Present when
`data-checked`	checked
`data-unchecked`	not checked
`data-indeterminate`	indeterminate
`data-disabled`	disabled
`data-readonly`	read-only
`data-required`	required
`data-valid`	in a Field: validated and valid
`data-invalid`	in a Field: validated and invalid
`data-dirty`	in a Field: checked state differs from initial
`data-touched`	in a Field: has been blurred
`data-filled`	in a Field: checked
`data-focused`	in a Field: focused

Checkbox.Indicator

Shown while checked or indeterminate. The styled version renders a check (or dash) icon by default. Renders <span>.

Prop	Type	Default	Description
`keepMounted`	`boolean`	`false`	Keep in the DOM while unchecked.

Data attribute	Present when
`data-checked`	checked
`data-unchecked`	not checked
`data-indeterminate`	indeterminate
`data-disabled`	disabled
`data-readonly`	read-only
`data-required`	required
`data-valid`	in a Field: validated and valid
`data-invalid`	in a Field: validated and invalid
`data-dirty`	in a Field: checked state differs from initial
`data-touched`	in a Field: has been blurred
`data-filled`	in a Field: checked
`data-focused`	in a Field: focused
`data-starting-style`	animating in
`data-ending-style`	animating out

Keyboard

Key	Action
`Space`	Toggles the checkbox.