Checkbox
A checkbox records a yes or no that the form collects and submits later, and it owns its label and its error message.
Installation
npx shadcn@latest add @flyingsalmon/checkboxUsage
import { Checkbox } from '@/components/ui/checkbox'
export function CheckboxUsage() {
return <Checkbox label="Include Sintra" defaultChecked />
}Examples
States
From the top: unchecked, checked, indeterminate, disabled, and disabled and checked. Checked and indeterminate share one orange fill, so a mixed state reads as part of the same control. There is one size and no loading state: a checkbox states intent, and the submit button shows the busyness.
Select all
The parent takes true, false, or "indeterminate" from what its children hold. Toggle the parent and the mark morphs between the check and the dash.
Error
The border, the focus ring, and the label turn red and the message appears below. A checked box keeps the red fill, so the whole control carries one colour.
Read the policy to continue
The policy changed today. Read it again.
In a form
Press Book trip without ticking the box, then tick it and try again. The app validates; the checkbox shows the message, and the card shows the result.
Guidelines
When to use
- To record a yes or no that a form collects and submits later, such as accepting a policy.
- To pick any number of options from a short list, each one independent of the others.
When not to use
- Use Switch for a setting that takes effect the moment it flips. A switch shows that it applies at once and shows its own busyness.
- Use Radio group when exactly one option must be chosen, because a checkbox cannot enforce a single answer.
- Use Combobox to pick several options from a long list, where a column of boxes is too tall to scan.
Do and don’t
- DoWrite the label so a tick reads as yes: "Tell travellers when the itinerary changes".A ticked box then means agreement, and nobody has to work out what an unticked one means.
- Don’tWord a label in the negative, such as "Don’t send me updates".A tick on a negative makes the traveller undo a double negative before they know what they agreed to.
- DoStack independent options in one column, each naming its own subject: "Day 3 · 12 Oct: museum".The list reads as a set of sentences, and each box stands on its own without a heading to decode it.
- DoShow the mixed state only on a parent whose children differ.It tells the traveller that some of the group is selected, and a click resolves it to all or none.
Accessibility
| Key | Description |
|---|---|
| Tab | Moves focus to the box. A disabled checkbox leaves the tab order. |
| Space | Toggles the box. An indeterminate box resolves to checked. |
Clicking the label toggles the box, so the click target covers both. An indeterminate box reports aria-checked="mixed". An error sets aria-invalid and links the message through aria-describedby, keeping any description you pass. The focus ring appears on keyboard focus only. required marks the label and sets aria-required; the validation itself stays with your app. The accessibility page covers the rules every component follows.
API
Checkbox
Also takes every <button> attribute. Checkbox ships no group, so grouping is the app’s job. The fields page describes the label, error, and wrapper behaviour that every field shares.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | – | The text beside the box. It is part of the click target and the accessible name, so give every box one: nearby text names nothing. |
| error | string | – | Turns the control red and shows the message below it. |
| checked | boolean | "indeterminate" | – | Controls the box. Pass "indeterminate" for a parent whose children are mixed. |
| defaultChecked | boolean | "indeterminate" | false | The starting state when the app does not control it. |
| onCheckedChange | (checked: boolean | "indeterminate") => void | – | Called with the next state after each toggle. |
| required | boolean | false | Marks the label and sets aria-required. It does not block submission. |
| disabled | boolean | false | Dims the box and its label and removes them from the tab order. |
| className | string | – | Styles the wrapper that holds the box, label, and message, not the box itself. |