Checkbox
StableA single on or off choice with its label next to the box, submitted with a form. Supports a mixed state for a parent that controls a partly checked group.
When to use
Use it for
- An independent yes or no that takes effect when the form is saved: agree, include, require.
- Several independent options under one question: put them in a CheckboxGroup.
- Selecting rows in a Table (with a parent checkbox in the header for select all).
Not for
- A setting that applies immediately: use Switch.
- One choice among exclusive options: use RadioGroup.
- A command (Delete, Publish): use Button.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
Phrase the label as the positive case
Checked means the label is true. "Notify reviewers" reads cleanly; a negative label makes users double-check.
Use the description for consequences
Keep the label short and explain the effect underneath.
Negative labels
"Do not send notifications" checked means off. Users have to think twice.
A checkbox that acts immediately
If ticking it changes something right away, it is a Switch.
Accessibility
- Base UI Checkbox: role checkbox, Space toggles, aria-checked is true, false or mixed (indeterminate).
- The whole label row is the click target; the label text is the accessible name (aria-labelledby) and the description is linked with aria-describedby.
- The box edge uses color.border.strong (3:1 against surfaces); checked uses the ink fill with a white check (4.5:1 or more).
- Indeterminate shows a dash, so mixed is not conveyed by color.
- invalid adds a danger edge; always pair it with an error message in the group or form.
Anatomy and tokens
Read from packages/react/src/components/Checkbox/Checkbox.module.css at build time. Every value is a token: open one to see its
alias chain in both themes.
- Label row (click target)
.item - Checkbox box
.box - Label row (click target), hover
@media (hover: hover) .item:hover .box:not([data-disabled], [data-checked], [data-indeterminate]) - Label row (click target), hover
@media (hover: hover) .item:hover .box[data-checked]:not([data-disabled]), .item:hover .box[data-indeterminate]:not([data-disabled]) - Checkbox box, focus
.box:focus-visible - Checkbox box
.box[data-checked], .box[data-indeterminate] - Checkbox box
.box[aria-invalid="true"], .box[data-invalid] - Check or dash indicator
.indicator - text
.text - Label text
.label - Description
.description - Label row (click target)
.item:has([data-disabled]) - Label row (click target)
.item:has([data-disabled]) .description - Checkbox box
.box[data-disabled]
Props
Parsed from the TypeScript types in packages/react/src/components/Checkbox/Checkbox.tsx, so this table cannot drift from the
code.
| Prop | Type | Default | Description |
|---|---|---|---|
label required | ReactNode | none | Visible label next to the box. Clicking it toggles the checkbox. |
description | ReactNode | none | Secondary text under the label, linked with aria-describedby. |
checked | boolean | none | No description in the code yet. |
defaultChecked | boolean | none | No description in the code yet. |
onCheckedChange | (checked: boolean) => void | none | No description in the code yet. |
indeterminate | boolean | none | Mixed state, for a parent that controls a partly checked group. Announced as "mixed". |
parent | boolean | none | Inside a CheckboxGroup with allValues: this checkbox selects or clears the whole group. |
value | string | none | Value submitted with the form, and the item id inside a CheckboxGroup. |
name | string | none | No description in the code yet. |
disabled | boolean | none | No description in the code yet. |
readOnly | boolean | none | No description in the code yet. |
required | boolean | none | No description in the code yet. |
invalid | boolean | false | Marks the checkbox invalid (red edge). Pair it with an error message on the group or form. |
id | string | none | No description in the code yet. |
className | string | none | No description in the code yet. |
Playground
Change the props and see the real Checkbox update. Controls are generated from the TypeScript props; nothing here changes the system.
<Checkbox defaultChecked label="Notify reviewers when I open a pull request" />Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open Checkbox in Storybook) .
Embed Storybook stories here (6)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay
empty.
Default
Checked
Indeterminate
WithDescription
Disabled
AllStates
Changelog
- New
Forms: Field (label, description, error wired by Base UI Field) and Input rebuilt on it (prefix, suffix, sizes; label, hint and error props kept). New Textarea (autosize, character count), Select (groups, descriptions), Combobox (filtering, async loading and empty states, multiple with chips), Checkbox (indeterminate, parent), CheckboxGroup, RadioGroup, Switch, Slider (single and range), NumberField (steppers, units) and Form (server errors with a focusable error summary, FormActions footer).
Unreleased (current version 0.1.0, no release tagged yet) , Oct 17, 2026
- New
Overlays: Dialog (sizes, scrolling body, footer, close last in focus order), AlertDialog (destructive confirmations, async confirm), Drawer (start, end, bottom with swipe), Popover, Tooltip with TooltipProvider, Menu (icons, shortcuts, groups, submenus, checkbox and radio items, danger items). Every popup carries the theme, brand and density scope. Adds menu and drawer component tokens.
Unreleased (current version 0.1.0, no release tagged yet) , Oct 17, 2026
- New
Bridge token system v1. Adds a brand mapping layer (`bridge` default, `ocean` alternate) between primitives and semantic tokens, a component tier (button, input, checkbox, switch, slider, card, popup, dialog, tooltip, toast, table, tabs, progress, nav), comfortable and compact density, motion durations and easings with a reduced-motion override, layers (z-index), icon sizes, breakpoints, a 1.2 type scale from 14px with tracking tokens, and self-hosted IBM Plex Sans and Mono (`@bridge-ds/tokens/fonts.css`). Primitives are regenerated in OKLCH on one lightness ladder. The build now writes `dist/resolved.json` and fails when any pair in `contrast.checks.json` drops below its WCAG minimum in any brand and theme. Fixes `color.border.strong` against `color.surface.default` (now at least 3:1 in both themes).
Unreleased (current version 0.1.0, no release tagged yet) , Oct 17, 2026