Components

Checkbox

A control for selecting one or more independent options.

Installation

Choose the package when you want centralized updates, or copy the source through the registry when you want local ownership.

@constructive-io/ui

Install the package, import its global tokens once, then use this exact subpath.

# install

pnpm add @constructive-io/ui

# app/globals.css

@import '@constructive-io/ui/globals.css';

# import

import { Checkbox } from '@constructive-io/ui/checkbox';

When to use

Use Checkbox for an independent choice, a form acknowledgment, or selecting any number of options from a set.
Use Radio Group when exactly one option may be selected. Use Switch when changing the value should take effect immediately as a setting.

Basic usage

Associate Checkbox with a visible Label by matching id and htmlFor. Use defaultChecked when the control can own its initial value.

npm source

tsx

'use client';
import { Checkbox } from '@constructive-io/ui/checkbox';
import { Label } from '@constructive-io/ui/label';
export function BasicCheckboxDemo() {
    return (<div className="flex items-center gap-2">
        <Checkbox id="checkbox-terms" name="terms" required/>
        <Label htmlFor="checkbox-terms">Accept the terms of service</Label>
      </div>);
}

Controlled and uncontrolled checked state

Use defaultChecked when Checkbox can own its state. Pass checked and onCheckedChange when application state is authoritative; indeterminate is a separate mixed-state signal.

Controlled and uncontrolled checked state

Email notifications

Notifications are enabled.

Examples

Indeterminate selectionSet indeterminate on a parent choice when only some of its child choices are checked.

Accessibility

Give every Checkbox an accessible name with a visible Label, an enclosing label, aria-label, or aria-labelledby.
Wrap related choices in a fieldset with a legend so the set has a shared accessible name. Keep each Checkbox individually labeled.
Indeterminate communicates a mixed visual and semantic state but does not calculate child values. Update the parent and child checked states together in application logic.

API Reference

Constructive-specific behavior is listed here. Each part links to its inherited platform or primitive contract.

Checkbox

Base UI checkbox root with a built-in control, check indicator, mixed-state indicator, and hidden form input.

Prop	Type	Default	Description
checked	boolean	—	Controlled checked state.
defaultChecked	boolean	false	Initial checked state.
onCheckedChange	(checked: boolean, eventDetails) => void	—	Runs when the checked state changes.
indeterminate	boolean	false	Shows and exposes the mixed state independently of checked.
disabled	boolean	false	Prevents interaction and form changes.
parent	boolean	false	Marks the control as a parent when it participates in Base UI Checkbox Group.
name	string	—	Name used by the hidden form input.
value	string	—	Value submitted when the checkbox is checked.
uncheckedValue	string	—	Optional value submitted when the checkbox is unchecked.

Also accepts Base UI Checkbox props.