Checkbox

An accessible checkbox with support for indeterminate state, group composition, and form integration.

Features

Controlled or uncontrolled
Indeterminate state
Group composition
Form integration
Headless styling

Installation

npm install @ariaui/checkbox

Examples

Each block is its own live example and snippet: basic control, label + description, disabled, a controlled Checkbox.Group list, and card-style Checkbox.Item cells.

Styling uses semantic tokens (for example border-border, data-[state=checked]:border-primary, and checked-state background utilities).

Basic

Single checkbox with an associated label. Style checked state with data-[state=checked] utilities.

Preview

No preview output yet.

live.tsxReady

With description

Stack a short helper paragraph next to the control; keep the visible label wired with htmlFor.

Preview

No preview output yet.

live.tsxReady

Disabled

Use the disabled prop on Checkbox.Root; the label picks up peer-disabled styles.

Preview

No preview output yet.

live.tsxReady

Group

Controlled Checkbox.Group with Checkbox.Item rows and string[] state.

Preview

No preview output yet.

live.tsxReady

Box group

Card-style Checkbox.Item cells for richer subscription-style choices.

Preview

No preview output yet.

live.tsxReady

Anatomy

tsx

import * as Checkbox from "@ariaui/checkbox";

export default function Example() {
  return (
    <Checkbox.Group>
      <Checkbox.Root>
        <Checkbox.Indicator />
      </Checkbox.Root>
      <Checkbox.Item>
        <Checkbox.Indicator />
      </Checkbox.Item>
    </Checkbox.Group>
  );
}

API Reference

Root

Interactive checkbox button with state management. Renders a `button` with `role="checkbox"`. Also available as `Item` for use inside `Group`.

Prop	Type	Default
checked	boolean	—
defaultChecked	boolean	false
onCheckedChange	(checked: boolean) => void	—
indeterminate	boolean	false
disabled	boolean	false
name	string	—
value	string	—
required	boolean	—

Attribute	Values
role	checkbox
aria-checked	true \| false \| mixed
[data-state]	checked \| unchecked \| indeterminate
[data-disabled]	Present when disabled

Indicator

Visual indicator rendered only when checked or indeterminate. Typically contains a checkmark or minus icon.

Prop	Type	Default
forceMount	boolean	false

Attribute	Values
[data-state]	checked \| unchecked \| indeterminate

Group

Multi-select group that manages a `string[]` of checked values. Renders a `div` with `role="group"`. Child Items derive their checked state from the group.

Prop	Type	Default
value	string[]	—
defaultValue	string[]	[]
onValueChange	(value: string[]) => void	—
disabled	boolean	false
name	string	—
required	boolean	—

Attribute	Values
role	group
[data-disabled]	Present when disabled

Keyboard

Shortcut	Action
`Space`	Toggle the focused checkbox between checked and unchecked.
`Tab`	Move focus to the next focusable element.
`Shift`+`Tab`	Move focus to the previous focusable element.

Accessibility

The Checkbox component implements the WAI-ARIA Checkbox pattern:

Renders a button with role="checkbox" and aria-checked reflecting the current state.
aria-checked="mixed" communicates the indeterminate state to assistive technology.
Disabled checkboxes set aria-disabled="true" and are removed from the tab order.
Checkbox.Group renders with role="group" — provide aria-label or aria-labelledby to name the group.

Always pair with a label

A checkbox without a visible <label> or aria-label is inaccessible. Use htmlFor on the label matching the checkbox id, or wrap the checkbox in a <label> element.