Checkbox

Playground

Installation

pnpm add @tessinaui/ui

Usage

import { Checkbox, CheckboxGroup } from "@tessinaui/ui";

{/* Standalone */}
<Checkbox label="Accept terms and conditions" />

{/* Controlled */}
<Checkbox
  checked={accepted}
  onCheckedChange={(val) => setAccepted(val as boolean)}
  label="Accept terms"
/>

{/* With description and error */}
<Checkbox
  label="Accept terms"
  required
  errorMessage="You must accept the terms to continue."
/>

{/* Mobile settings row: text leading, control trailing, whole row tappable */}
<Checkbox label="Deals and offers" labelPlacement="start" fullWidth />

When to use

• Checkbox — pick any number of options from a set, or a single yes/no that is submitted with a form (terms consent).
• Radio — exactly one of a set.
• Switch — a standalone setting with an immediate effect, no form submit.
• Chip (filter) — multi-select directly over the content it filters.

Write labels as short positive fragments in sentence case ("Send me updates", never "Don't send me emails"), no trailing punctuation. Labels wrap — they are never truncated.

Examples

Default

A basic checkbox with a label. The label, the box, and the space between them are one tap target.

Sizes

Five sizes from xs to xl; box, mark, and label scale together.

Intents

Semantic colors — none, error, warning, success, and info. The unchecked warning border and all helper text step to accessible token shades (see Accessibility).

States

Unchecked, checked, indeterminate, disabled, read-only, and loading. Read-only stays at full opacity and keeps keyboard focus but refuses interaction; loading shows a spinner in the box and reports aria-busy.

Description and error

Helper text below the label, or a validation message with an alert icon. The message is announced politely and colored by intent — with no explicit intent it defaults to error styling, so intent="warning" + errorMessage is a warning message, not an error repainted red.

Terms with links

label accepts ReactNode: links inside the label navigate without toggling the checkbox.

Group

A CheckboxGroup renders a single labeled <fieldset>; value/onValueChange manage the checked set by each child's name.

Select all (parent)

Pass parent to one checkbox inside a controlled group with allValues — Base UI derives its checked/indeterminate state and the mixed → all → none → last-partial cycle. Do not wire checked/indeterminate on the parent yourself.

Mobile rows

fullWidth + labelPlacement="start" is the settings-row shape: text leading, control trailing, the entire row one tap target.

Contact list

Checkbox composed with Avatar for selecting people.

Cards

CheckboxCard turns the entire surface into a selectable option with a title, description, and corner indicator.

API Reference

Checkbox

Deprecated: labelPosition ("left" \| "right") — maps onto labelPlacement (left → start), removed next minor.

All other props (inputRef, uncheckedValue, nativeButton, form, render, ARIA/data attributes) are forwarded to the Base UI Checkbox.Root — a <span role="checkbox"> with a hidden <input> beside it.

CheckboxGroup

CheckboxCard

Plus all Base UI root props (checked, value, disabled, …). CheckboxCardGroup adds columns (1–4), the same label/description/errorMessage fieldset chrome, and propagates size/intent/rounded/motion.

CheckboxSkeleton

size, rounded, labelPlacement, fullWidth, showLabel, showDescription, showError, labelChars, descriptionChars, dir — mirrors the real boxes exactly (the frame is the checkbox's own cva).

Do / Don't

• Do use one Checkbox for a submitted yes/no (terms); don't use a Switch there — switches imply immediate effect.
• Do give a parent checkbox a controlled group with allValues; don't hand-wire its checked/indeterminate.
• Do keep labels positive ("Email me"); don't negate ("Don't email me") — checking a negative is a double negative.
• Do use errorMessage on the group for "pick at least one"; don't mark every child invalid.
• Do use rounded="full" for circular mobile selection indicators; don't invent a shape prop or confuse circles with radios in forms.

Accessibility

Pattern: WAI-ARIA APG Checkbox (tri-state for parent).

• The row is a wrapping <label>: box, text, and gap are one click/tap target; nested links in a rich label navigate without toggling.
• Accessible name = label content. The description is aria-hidden inside the label and reaches the control via aria-describedby (hidden referents resolve); the required asterisk is decorative — the control's own required/aria-required carries the semantic.
• errorMessage renders in the text column as an aria-live="polite" region, sets aria-invalid, and joins aria-describedby; it cannot join the accessible name because the name comes from the label text span via aria-labelledby.
• aria-checked="mixed" for indeterminate; a parent checkbox announces the mixed state and controls the set.
• Groups render one <fieldset> captioned by its <legend> — a single role="group" announcement (the fieldset is the Base UI group element).
• Disabled = aria-disabled, removed from the tab order. Read-only = focusable, aria-readonly, not operable (review-mode pattern). Loading = aria-busy + refused interaction.
• Touch targets: 44×44px hit area per box on touch viewports with ≥44px row pitch (overlays shrink to the 24px WCAG 2.5.8 minimum at md+ so stacked rows never overlap); fullWidth makes the whole row the target.
• Contrast (hard-gated in pnpm audit:contrast, light + dark): unchecked border --outline-border 3.03:1/3.01:1; warning unchecked border + helper text use warning-tinted-foreground (7.14:1 light); helper/error text mirrors Label's map; checked fills use the locked on-* glyph pairs; card selected ink 4.72–13.97:1.
• Forced colors (Windows High Contrast): states map to SelectedItem/SelectedItemText/GrayText so checked and unchecked stay distinguishable.
• Reduced motion: the mark's 150ms fade/zoom, press scale, and spinner rotation are all disabled or substituted under prefers-reduced-motion.
• AT matrix: VoiceOver + NVDA passes pending (status stays beta until both are on record).