Skip to content
WunderUI

Checkbox

Free

Let people turn one option on or off, or pick several from a list.

npx wunderui-cli add checkbox

Playground

Installation

bash
npx wunderui-cli add checkbox

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import { Checkbox } from "@/components/ui/checkbox"
import type { CheckboxProps } from "@/components/ui/checkbox"

Then use it:

tsx
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.

Keyboard interactions

A checkbox is one tab stop. Space toggles it, and Enter does nothing, as on a native checkbox.

TaborShiftTab
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.

  • data-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.

  • data-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"
  • 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.

PropTypeDefaultDescription
checkedbooleanundefinedWhether the box is ticked. Pass it together with to control the box; use to let the box keep the value.
defaultCheckedbooleanfalseWhether 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.
indeterminatebooleanfalseShows 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.
labelReactNode—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.
descriptionReactNode—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.
errorReactNode—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.
wrapperClassNamestring—Class names for the row (or, with , for the wrapper around the row and the message). still goes to the box.
disabledbooleanfalseThe box ignores clicks and keys, is dimmed to 40 % and is skipped by Tab.
readOnlybooleanfalseThe box keeps its value and cannot be ticked or unticked. It is announced as read-only.
requiredbooleanfalseA 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.
idstring—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.
namestringundefinedThe name of the field when a form is sent.
valuestring—The value sent with the form when the box is ticked. The default is .
uncheckedValuestring—The value sent with the form when the box is not ticked. By default an unticked box sends nothing, like a native checkbox.
formstring—The id of the form that owns the hidden input, for a box that is rendered outside the form.
inputRefRef<HTMLInputElement>—A ref to the hidden . The component also copies and onto it.
parentbooleanfalseMarks 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.
nativeButtonbooleanfalseSet it to when swaps the element for a native .
renderReactElement | (props, state) => ReactElement—Replaces the element of the box with another tag or component. Accepts an element or a function that returns one.
classNamestring | (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.
styleCSSProperties | (state) => CSSProperties | undefined—Inline style for the box, an object or a function of the state.

PropTypeDefaultDescription
label requiredReactNode—
appearance"brand" | "neutral"— fills the checked box with the brand colour; fills it with the inverse (black/white) surface.
checkedbooleanundefinedWhether the checkbox is currently ticked. To render an uncontrolled checkbox, use the prop instead.
defaultCheckedbooleanfalseWhether the checkbox is initially ticked. To render a controlled checkbox, use the prop instead.
descriptionReactNode—A second line under the label in the tertiary colour.
disabledbooleanfalseWhether the component should ignore user interaction.
errorReactNode—Error message under the row. Sets and on the box and turns its rim red.
formstring—Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
idstring—The id of the input element.
indeterminatebooleanfalseWhether the checkbox is in a mixed state: neither ticked, nor unticked.
inputRefRef<HTMLInputElement>—A ref to access the hidden element.
namestringundefinedIdentifies the field when a form is submitted.
nativeButtonbooleanfalseWhether 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.
parentbooleanfalseWhether the checkbox controls a group of child checkboxes. Must be used in a Checkbox Group.
readOnlybooleanfalseWhether the user should be unable to tick or untick the checkbox.
requiredbooleanfalseWhether the user must tick the checkbox before submitting a form.
uncheckedValuestring—The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
valuestring—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…
wrapperClassNamestring—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.

MCPget_component("checkbox")
Installnpx wunderui-cli add checkbox

The full library index for assistants is at /llms.txt.