Checkbox
A control for toggling between checked and unchecked, built on Base UI. Supports an indeterminate state and three sizes.
Playground
<Checkbox defaultChecked />Preview
A single self-contained component – no separate indicator part to compose. Use defaultChecked for uncontrolled state or checked / onCheckedChange for controlled state.
<Checkbox />
<Checkbox defaultChecked />Installation
npx shadcn@latest add https://espresso-base-ui.vercel.app/r/checkbox.jsonUsage
import { Checkbox } from "@/components/ui/checkbox"<Checkbox
defaultChecked
onCheckedChange={(checked) => console.log(checked)}
/>Sizes
size offers default (16px), sm (14px) and xs (13px); the indicator icon scales with the box. An invisible hit area extends well beyond the box on every size.
<Checkbox size="xs" defaultChecked />
<Checkbox size="sm" defaultChecked />
<Checkbox defaultChecked />Indeterminate
The indeterminate prop renders a filled box with a dash – use it for "select all" controls when only some children are checked.
<Checkbox indeterminate />
<Checkbox size="sm" indeterminate />
<Checkbox indeterminate disabled />Disabled and invalid
disabled mutes the box and blocks pointer events. Set data-invalid (or place the checkbox inside a Field marked invalid) for a destructive border and ring.
<Checkbox disabled />
<Checkbox disabled defaultChecked />
<Checkbox data-invalid="true" />
<Checkbox data-invalid="true" defaultChecked />API reference
Checkbox forwards every Base UI Checkbox.Root prop – including name, value, required and inputRef for form integration – and adds the props below.
Checkbox
| Prop | Type | Default | Description |
|---|---|---|---|
| size | "xs" | "sm" | "default" | "default" | Box size – 13px, 14px or 16px – with a matching indicator icon size. |
| checked | boolean | – | Controlled checked state; pair with onCheckedChange. |
| defaultChecked | boolean | false | Initial checked state when uncontrolled. |
| onCheckedChange | (checked, event) => void | – | Called when the checked state changes. |
| indeterminate | boolean | false | Mixed state – fills the box with a dash indicator and reports aria-checked="mixed". |
| disabled | boolean | false | Prevents interaction and applies the muted disabled styling. |
| data-invalid | string | – | Marks the checkbox invalid ("true") for destructive border and ring styling. |
Accessibility & styling hooks
Base UI renders a button with role="checkbox" and the correct aria-checked value ("mixed" when indeterminate), plus a hidden input for form submission. State is mirrored as data attributes – data-checked, data-unchecked, data-indeterminate, data-disabled – alongside data-slot="checkbox" and data-size on the root and data-slot="checkbox-indicator" on the indicator. When nested in a Field, the group-data-[invalid=true]/field selectors pick up the field's invalid state automatically. The checkboxVariants cva helper is also exported:
import { checkboxVariants } from "@/components/ui/checkbox"
<span className={cn(checkboxVariants({ size: "sm" }))} />