Checkbox
FreeLet people turn one option on or off, or pick several from a list.
npx wunderui-cli add checkboxPlayground
Installation
npx wunderui-cli add checkboxWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Checkbox } from "@/components/ui/checkbox"
import type { CheckboxProps } from "@/components/ui/checkbox"Then use it:
import { Checkbox } from "@/components/ui/checkbox"
export function Newsletter() {
return <Checkbox id="updates" label="Email me about new releases" />
}Expected result: You see one empty box with the label Email me about new releases. A click on the box or on the text ticks it.
When to use
Use Checkbox for
- An on or off choice in a form, such as accepting terms or remembering a device
- Picking several items from a list, such as topics or the rows of a table
- A select-all box that shows a mixed state while only some rows are chosen
Use something else for
- Switch for a setting that takes effect at once, without a Save button
- Radio Group for one choice out of several options
- Checkbox Button Group for a multi-select that reads as a row of buttons
- Selector Item for a whole row with a title, a description and a checkbox
Values
A checkbox is unchecked or checked. Indeterminate is not a third choice but the mark of a select-all box while only some rows are chosen.
Appearance
Brand fills the checked box with the brand colour. Neutral fills it black in light mode and white in dark mode, where the brand colour would compete.
States
Hover and pressed are real states: move the pointer over a box, or press Tab to see the focus ring. A disabled box stays readable and is skipped by Tab.
Label and description
Every checkbox needs a visible label, so a click on the text toggles it and a screen reader announces both. Without a label, description or error it is the bare box, for a table row.
Error and invalid
A failed rule turns the border red and a message under the box says what to do. The message sits outside the label, so it is not read as part of the name.
Accept the terms to create your account.
Keyboard interactions
A checkbox is one tab stop. Space toggles it, and Enter does nothing, as on a native checkbox.
- TaborShift+Tab
- Moves focus to the next or previous checkbox in the order they are written. A disabled box is skipped.
- Space
- Toggles the focused checkbox and calls . A box that is stays a dash until you clear the prop.
Behavior and motion
What the checkbox does itself, and what it leaves to the page.
- Two elements, one control
- The visible box has the checkbox role and reports its checked state. Next to it Base UI renders a hidden input that carries the name, value and form state, with the labels copied onto it.
- Controlled or not
- Pass checked and a change handler to own the value, or a default to let the box keep it. The handler gets the new value as a boolean.
- Indeterminate
- Indeterminate shows a dash and reports a mixed state. You set and clear it, and it wins over checked until you remove it, so work it out from the rows you control.
- One component, two shapes
- Without a label, description or error, Checkbox renders the bare box. With one it renders the row, so a click on the text toggles the box, and the box keeps its focus when an error appears.
- Disabled
- Disabled dims the box to 40 %. In a row the label and description dim with it, once, and the row shows the not-allowed cursor.
- Hit area
- The click area reaches 12 px to the sides and 8 px above and below the 16 px box, so a near miss still ticks it.
- Invalid
- An error marks the box invalid, turns the border and focus ring red even when ticked, and shows the message under the row. Without row props, the message is yours to write.
- In a form
- With a name, the box submits its value (default on) when ticked, and nothing when not, unless you set an unchecked value. Required asks for a tick before the form is sent.
- Motion
- Fill and border change quickly. When the box is ticked the check is drawn in slowly, and unticking reverses it quickly.
- Reduced motion
- With reduced motion transitions are limited to colour and opacity, so the check fades in instead of being drawn.
Anatomy
The parts the component is made of. Each one renders a you can target from CSS.
- 1data-slot="checkbox-field"
The box: a 16 px square with a 4 px radius. Checked or indeterminate it is filled with the brand colour, and its hit area reaches 12 px sideways and 8 px up and down.
- 2data-slot="checkbox-indicator"Optional
The check, or a dash while indeterminate. Its stroke is drawn in when the box is ticked, and Checkbox renders it for you.
- data-slot="checkbox"
- 3
The text that names the box. With a label the whole row is the click target, and without one the box needs an aria-label.
- Optional
A line under the row in 12 px error colour, indented to the text. It sits outside the label, so it is not part of the box's name, and it marks the box invalid and is linked with aria-describedby.
- Optional
Best practices
- Do
Give every checkbox a visible label. It is joined to the box, so a click on the text toggles it and a screen reader announces the label with the value.
- Do
Write the label as the choice itself, like Email me about new releases. Put a sentence of detail in the description under it.
- Do
Use indeterminate on a select-all box while only some rows are chosen. Work it out from the rows and state its scope, like Select all acts on the 5 members shown.
- Do
State the rule of a group above it, and put the error under the group, not on one row, like Choose at least two topics.
- Do
Show the error on a required box only after the first try to continue, and say what to do, like Accept the terms to create your account.
- Don’t
Don't import CheckboxField in new code. It is a deprecated alias of Checkbox, so use Checkbox with the same props.
- Don’t
Don't build a checkbox from a styled div. The component already handles Space, the focus ring and the larger hit area around the small box.
- Don’t
Don't use a checkbox for a setting that applies at once. A box looks like part of a form that is saved later, so use a Switch.
- Don’t
Don't offer indeterminate as a choice. It only displays a partial selection, and people can never pick it.
- Don’t
Don't show the error before the first try. A red box on load reads as a mistake the person has not made yet.
API reference
Checkbox wraps the Base UI checkbox and takes the props below plus every native attribute, with aria props reaching the box. A label, description, error or wrapper class turns the bare box into a row.
The box: a 16 px square with a 4 px radius. Checked or indeterminate it is filled with the brand colour, and its hit area reaches 12 px sideways and 8 px up and down.
| Prop | Type | Default | Description |
|---|---|---|---|
| checked | boolean | undefined | Whether the box is ticked. Pass it together with to control the box; use to let the box keep the value. |
| defaultChecked | boolean | false | Whether the box starts ticked, when the box keeps its own value. |
| onCheckedChange | (checked: boolean, eventDetails) => void | — | Called when the box is ticked or unticked, with the new value as a boolean. |
| indeterminate | boolean | false | Shows a dash instead of the check and sets . Use it on a select-all box while only some rows are chosen. It wins over until you clear it. |
| appearance | "brand" | "neutral" | — | fills the ticked box with the brand colour; fills it with the inverse surface, black in light mode and white in dark mode. |
| label | ReactNode | — | The visible name of the box, to its right. Joined to the box with in one . Any of , , and makes Checkbox render the row instead of the bare box. |
| description | ReactNode | — | A second line under the label in 12 px tertiary text. It is part of the label, so it dims with it when the box is disabled. |
| error | ReactNode | — | The message under the row in the error colour. Sets on the box, turns its border red and is linked with . It sits outside the label. |
| wrapperClassName | string | — | Class names for the row (or, with , for the wrapper around the row and the message). still goes to the box. |
| disabled | boolean | false | The box ignores clicks and keys, is dimmed to 40 % and is skipped by Tab. |
| readOnly | boolean | false | The box keeps its value and cannot be ticked or unticked. It is announced as read-only. |
| required | boolean | false | A tick is needed before a form that holds the box can be sent. It does not draw anything by itself: pass to show the message. |
| id | string | — | The id of the hidden input. With it joins the label to the box (from unless you give one); otherwise point the of a at it. |
| name | string | undefined | The name of the field when a form is sent. |
| value | string | — | The value sent with the form when the box is ticked. The default is . |
| uncheckedValue | string | — | The value sent with the form when the box is not ticked. By default an unticked box sends nothing, like a native checkbox. |
| form | string | — | The id of the form that owns the hidden input, for a box that is rendered outside the form. |
| inputRef | Ref<HTMLInputElement> | — | A ref to the hidden . The component also copies and onto it. |
| parent | boolean | false | Marks a box that controls a group of child boxes. WunderUI does not ship a Checkbox Group, so leave it off and work out and from your rows, as the Select all example does. |
| nativeButton | boolean | false | Set it to when swaps the element for a native . |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the box with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the box's own. A string, or a function of the state. Use it for spacing such as , not to recolour the box. |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline style for the box, an object or a function of the state. |
| Prop | Type | Default | Description |
|---|---|---|---|
| label required | ReactNode | — | |
| appearance | "brand" | "neutral" | — | fills the checked box with the brand colour; fills it with the inverse (black/white) surface. |
| checked | boolean | undefined | Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the prop instead. |
| defaultChecked | boolean | false | Whether the checkbox is initially ticked. To render a controlled checkbox, use the prop instead. |
| description | ReactNode | — | A second line under the label in the tertiary colour. |
| disabled | boolean | false | Whether the component should ignore user interaction. |
| error | ReactNode | — | Error message under the row. Sets and on the box and turns its rim red. |
| form | string | — | Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form. |
| id | string | — | The id of the input element. |
| indeterminate | boolean | false | Whether the checkbox is in a mixed state: neither ticked, nor unticked. |
| inputRef | Ref<HTMLInputElement> | — | A ref to access the hidden element. |
| name | string | undefined | Identifies the field when a form is submitted. |
| nativeButton | boolean | false | Whether the component renders a native element when replacing it via the prop. Set to if the rendered element is a native button. |
| onCheckedChange | (checked, eventDetails) => void | — | Event handler called when the checkbox is ticked or unticked. |
| parent | boolean | false | Whether the checkbox controls a group of child checkboxes. Must be used in a Checkbox Group. |
| readOnly | boolean | false | Whether the user should be unable to tick or untick the checkbox. |
| required | boolean | false | Whether the user must tick the checkbox before submitting a form. |
| uncheckedValue | string | — | The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior. |
| value | string | — | The checkbox's value. Identifies it within a Checkbox Group, falling back to when omitted. When submitting a form, a checked box submits ; with no , it submits the… |
| wrapperClassName | string | — | Class names for the row (or, with , for the wrapper around the row and the message). |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("checkbox")npx wunderui-cli add checkboxThe full library index for assistants is at /llms.txt.