Content
- Labels are short and positive, in sentence case: “Show company”, “I currently work here”.
- A row's box is named for the row: “Select Leah Okonkwo”. The header's is “Select all”.
ExperimentalatomInputs
Checkbox
A box people tick: choosing rows, one option in a form, or several from a list.
import { … } from "@brdgapp/ui/components/checkbox"Usage
Checkbox is a box people tick. It has three jobs: choosing rows to act on together, turning on one option in a form (“I currently work here”), and picking several options from a list. Ticking it changes nothing until the form or the bulk action is used; for a setting that takes effect at once, use Switch. The usual mistake is a tiny box people miss, or a “Select all” that can't show when only some rows are chosen.
When to use
- One per row, plus “Select all” in the header, when people act on many rows at once.
- A single yes-or-no option inside a form that saves with a button: “I currently work here”.
- A list where people pick any number of options: which details to show on each person.
When not to use
- For a setting that takes effect the moment it's flipped. Use Switch instead.
- To pick exactly one option from a few. Use SegmentedControl instead.
- To filter a table column. Use ColumnFilterMenu instead.
The look comes from props
A component's appearance comes only from its own options (variant, size, color). className on a package component is for layout (mt-4, shrink-0, w-full), never for font size, color, padding, radius or hover. If the look needs a className, the component or the chosen option is wrong: fix that instead.
Anatomy
Box. 16px, 4px corners, outlined in
--text-mutedwhen empty. Its click area reaches 28px, past the box, invisibly.Mark. A white tick, or a dash when part-ticked, on
--primary-solid.Label. Optional. 14px
--text-primarybeside the box; clicking it ticks the box.Description. Optional. 12px
--text-mutedunder the label.
Examples
Choosing rows
Tick a few people. “Select all” is part-ticked while only some are chosen; clicking it chooses them all.
1 selected
- Leah Okonkwo
- Priya Natarajan
- Mei Lin Zhou
- Kwame Asante
One option in a form
The label sits beside the box, and clicking it ticks the box. Help goes under the label.
A list of options
Any number can be ticked. The group holds which ones.
Show on each person
Showing: company, linkedin
States
| Rest | Hover | Focus | Disabled | |
|---|---|---|---|---|
| Empty | ||||
| Ticked | ||||
| Part-ticked |
| State | What happens |
|---|---|
| Empty | Grey outline on white. |
| Hover | An empty box's outline darkens; a ticked box's fill darkens. |
| Ticked | Blue fill, white tick. |
| Part-ticked | Blue fill, white dash. Only for “Select all” when some, not all, rows are chosen. Clicking it ticks every row. |
| Focus | A soft blue ring around the box. |
| Disabled | 50% opacity, with its label; can't be ticked. |
Behavior
- Built on Base UI Checkbox. Space ticks the focused box; clicking the label ticks it too.
indeterminateshows the part-ticked dash. The screen sets it from the rows: some chosen, but not all.- CheckboxGroup holds the ticked options as a list of values (
value,onValueChange); each Checkbox inside gets avalue. classNameis for layout only. Never a size or color.
Do and don't
Do
Use Checkbox in a form that saves with a button: “I currently work here”.Don't
Use Checkbox for a setting that saves on its own. That's a Switch.Do
Write the label as the thing that's true when ticked: “Show LinkedIn link”.Don't
Write it as a question or a negative: “Don't hide LinkedIn?”.Do
Show “Select all” part-ticked when only some rows are chosen.Don't
Leave it empty, or ticked, when some rows are chosen.Accessibility
- Every box has a name: its
label, or anaria-labelwhen it stands alone in a row. - The description is read with the box.
- Part-ticked is announced as “mixed”.
- The empty outline is
--text-muted, above 3:1 in both themes. The light border tokens would be 1.2:1 and hard to see. - The click area is 28px, Bridge's smallest target, though the box is 16px.
| Keys | Action |
|---|---|
| Space | Ticks or unticks the focused box. |
| Tab | Moves to the next box or field. |
API reference
Checkbox
One box, with an optional label. Extends Base UI Checkbox props (checked, defaultChecked, onCheckedChange, disabled, name, value…).
| Prop | Type | Default | Description |
|---|---|---|---|
checked | boolean | — | Ticked or not, when the screen holds the state. |
onCheckedChange | (checked: boolean) => void | — | Called when it's ticked or unticked. |
indeterminate | boolean | false | Part-ticked: for “Select all” when only some rows are chosen. |
label | ReactNode | — | Text beside the box. Without it, set aria-label. |
description | ReactNode | — | A line of help under the label. |
value | string | — | Inside a CheckboxGroup: which option this box is. |
className | string | — | Layout only. |
CheckboxGroup
A list of options; holds which ones are ticked. Extends Base UI CheckboxGroup props.
| Prop | Type | Default | Description |
|---|---|---|---|
label | ReactNode | — | What the options are about. The group's name for screen readers. |
value | string[] | — | The ticked options. |
onValueChange | (value: string[]) => void | — | Called with the new list when one is ticked or unticked. |
defaultValue | string[] | — | The ticked options to start with, when the screen doesn't hold them. |
Lineage
What it's built from and where it's used, read from the code. When you change it, check these too.
- Built from
- Nothing else in the package
- Used by components
- None
- Used in patterns
- Selection and bulk actions
- Used in templates
- None