Checkbox
Toggle control for binary and indeterminate selection states.
Installation
The component is exported from @by/experience-system. Add the package with your package manager:
pnpm add @by/experience-systemIn this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.
Composition
Use a single Checkbox with an external Label (or Field) for naming:
Checkbox (button role)
└── CheckboxPrimitive.Indicator (internal — check / indeterminate icons)The experience system renders Radix Root with an inner face and Indicator; consumers do not render Indicator separately.
Usage
import { Checkbox } from '@by/experience-system';Checkbox is a client component ('use client'). Use it inside a Client Component or a dynamic import when using the Next.js App Router.
<Checkbox id="terms" required />Pair with Label htmlFor="terms" (or Field) so the control has an accessible name.
Examples
Overview
Default medium size with a Label.
Checked states
defaultChecked, boolean checked, and "indeterminate" for tri-state use cases.
Sizes
size small vs medium on the checkbox face.
API Reference
Checkbox wraps Radix Checkbox (@radix-ui/react-checkbox / radix-ui Checkbox.Root). The tables below summarize the Radix CheckboxProps surface; for the full primitive matrix (including inherited button behavior), see Radix Checkbox and MDN — button.
Checkbox
| Prop | Type | Default |
|---|---|---|
asChild | boolean | — |
checked | boolean | 'indeterminate' | — |
defaultChecked | boolean | 'indeterminate' | — |
disabled | boolean | — |
required | boolean | — |
onCheckedChange | (checked: boolean | 'indeterminate') => void | — |
size | small | medium | medium (Experience System extension on the face) |
Also inherits Primitive.button props from Radix except checked / defaultChecked, which are replaced by the Radix CheckedState typings above.
| Data attribute | Values |
|---|---|
data-slot | checkbox |
data-state | checked | unchecked | indeterminate (Radix) |
| Data attribute (indicator) | Values |
|---|---|
data-slot | checkbox-indicator |
Accessibility
Use an associated Label or aria-label so the checkbox has an accessible name. disabled removes pointer and keyboard interaction; required participates in constraint validation when inside a form. Indeterminate is visual and stateful—ensure parent/child relationships are clear in tri-state trees. See Radix Checkbox — accessibility.
Keyboard interactions
| Key | Description |
|---|---|
Space | Toggles checked state when the checkbox is focused. |
Enter | Does not submit by itself; use an explicit submit button in forms. |
Source in the repo: packages/experience-system/src/components/Checkbox/Checkbox.tsx. Agent-oriented contracts: packages/experience-system/src/components/Checkbox/Checkbox.instructions.md.
Registry examples
This @by-es item is a registry-only composite — live preview, installation steps, and source live on the dedicated page. See Registry for components.json setup and REGISTRY_TOKEN.
Checkbox list
Scrollable checklist with optional counts, expand/collapse, and a Done action.