Checkbox
Preview appears after the next Storybook update.
<Checkbox />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.
Content guidelines
- Sentence case, no trailing period on the label.
- Describe the result of checking it, not the control: "Notify reviewers", not "Check to notify".
- Descriptions are one short sentence.
From the code Generated from the component, not editable here.
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]
Motion and interaction
Checkbox animates on hover, check and uncheck. Try it in the preview at the top.
| When | What changes | Duration | Easing |
|---|---|---|---|
| Hover | Border and background | motion.duration.instant75 ms | motion.easing.standardsettles in place |
| Check and uncheck | Background, border, fade and movement | motion.duration.fast150 ms | motion.easing.enterstarts fast, lands softly |
With reduced motion turned on, every change happens at once.
From the code Generated from the component, not editable here.
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 |
|---|---|---|---|
labelrequired | 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
From the code Generated from the component, not editable here.
Changelog
- 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)
v1.0.0, Nov 11, 2026
- New
Push works like publishing a library in Figma: a Changes list grouped Variables and Components with a checkbox per item (all checked by default, select all per group), a Description that opens the pull request and every request, and one "Push for review"
v1.0.0, Nov 11, 2026
- Fix
Component specs for Figma: a content-box min-height or min-width counts its padding and border, as CSS draws it (checkbox, radio, switch, link rows were 3px short in Figma)
v1.0.0, Nov 11, 2026
- Fix
Component specs for Figma: a defaultValue list opens or checks its items, as Base UI does (an accordion draws only its open panels, a checkbox group checks the boxes it lists)
v1.0.0, Nov 11, 2026
- Fix
Library review, List: each family's select-all checkbox is always shown
v1.0.0, Nov 11, 2026
- Fix
Library review List: a piece decided on its own (two ways, a removal) shows its checkbox off, with a tooltip saying why
v1.0.0, Nov 11, 2026