Checkbox

Checkboxes select zero or more options in a visible group and support checked, unchecked, indeterminate, invalid, disabled, and read-only states.

Overview and decision boundary

Use Checkbox for grouped multi-selection and aggregate indeterminate state; use Switch for standalone boolean values.

Do not use Checkbox for mutually exclusive options or immediate on/off settings; use RadioGroup or Switch instead.

Visible collections

Include archived collectionsArchived collections remain visible in search results.Some collections are archivedThis selection represents a partial set of archived collections.Archived collections are unavailable

1import { FormGroup } from "@nerio-ui/ui";2import { Checkbox } from "@nerio-ui/ui/client";34<FormGroup title="Visible collections">5  <Checkbox defaultChecked label="Active collections" />6  <Checkbox label="Archived collections" />7</FormGroup>

Installation and imports

Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.

1pnpm dlx nerio add checkbox23import { Checkbox } from '@nerio-ui/ui/client';

Usage

1import { Checkbox } from '@nerio-ui/ui/client';23<Checkbox4  defaultChecked5  name="includeArchived"6  label="Include archived collections"7  description="Archived collections remain visible in search results."8/>910// Use indeterminate for an aggregate or partial selection.11<Checkbox aria-label="Partially selected" indeterminate />

Variants

Variant	Use
`Default`	One option in a visible multi-selection group.

Anatomy

Slot	Purpose
`field`	Optional wrapper that groups a Checkbox with its label and description.
`root`	Base UI checkbox control with checked, indeterminate, disabled, and read-only state.
`indicator`	Nerio icon adapter Check or Minus indicator.
`label`	Optional visible name connected to the control with aria-labelledby.
`description`	Optional supporting text connected with aria-describedby.

States

State	Behavior
`Unchecked`	Option is available but not selected.
`Checked`	Option is selected.
`Indeterminate`	Represents an aggregate or partial selection.
`Invalid`	Explicit invalid state maps to aria-invalid.
`Disabled`	Option is unavailable.
`Read-only`	Option remains visible but does not accept changes.

Motion

State changes should use shared motion tokens and preserve reduced-motion behavior.

Accessibility

Uses the Base UI Checkbox primitive for keyboard and checked-state behavior.
Use Checkbox only for grouped multi-selection; use Switch for standalone boolean values and RadioGroup for mutually exclusive choices.
Provide a visible label or accessible name with aria-label or aria-labelledby; label automatically connects the visible name.
Description automatically connects supporting text with aria-describedby, while explicit aria-describedby values are preserved.
Supports checked, defaultChecked, onCheckedChange, disabled, required, name, value, form, id, and aria-describedby through the Base UI root props.
Invalid state is explicit through invalid or aria-invalid and does not announce errors automatically.
Disabled state prevents interaction and reduces emphasis.
The Check and Minus indicators render through the Nerio icon adapter, including aria-checked=mixed for indeterminate state.

API

Prop	Purpose
`checked / defaultChecked / onCheckedChange`	Controlled and uncontrolled checked-state APIs from the Base UI root.
`label`	Optional visible name for a checkbox field row.
`description`	Optional supporting text displayed below label and announced as a description.
`name / value / form / required / disabled / readOnly`	Native form metadata is preserved through the Base UI root props.
`invalid`	Sets data-invalid and aria-invalid when true.
`className`	Extends the checkbox control, not the optional field wrapper.

Implementation contract

Contract	Value
`Registry item`	checkbox installs 7 Tailwind-first source files into the configured components directory.
`Base UI`	checkbox
`Registry dependencies`	None.
`Package dependencies`	@base-ui/react, @nerio-ui/adapters, clsx, react, tailwind-merge, tailwindcss

Styling contract

Contract	Value
`Authoring`	`Complete, statically detectable Tailwind CSS v4 recipes own component visuals.`
`Values`	`Semantic and component --n-* variables remain the canonical customization layer.`
`Overrides`	`Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically.`
`Residual CSS`	`Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer.`

Design notes

Use Checkbox for grouped multi-selection and aggregate indeterminate state; use Switch for standalone boolean values.

Do / do not

Use Checkbox for grouped multi-selection such as filters, permissions, or visible option lists.

Use Checkbox for a standalone yes/no value or mutually exclusive options; use Switch or RadioGroup instead.

Tokens

Group	Tokens	Controls
`Sizing`	`--n-checkbox-size`	Control size across density modes.
`Shape`	`--n-checkbox-radius`	Four-pixel corner radius for familiar checkbox geometry.
`Selected`	`--n-color-action-primary / --n-color-action-on-primary`	Selected surface and icon.
`Invalid`	`--n-input-border-danger`	Invalid border treatment.
`Focus`	`--n-focus-ring`	Visible keyboard focus treatment.