# Checkbox

A single choice that is on or off, with an indeterminate state for “some selected”.

- Category: Core Elements
- Page: https://wunderui.com/components/checkbox
- Tier: Free

## Install

```bash
npx wunderui-cli add checkbox
```

## Import

```tsx
import { Checkbox, CheckboxField, CheckboxFieldProps, CheckboxProps } from "@/components/ui/checkbox"
```

## Minimal usage

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.

## Usage

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

export function Example() {
  return (
    <Checkbox id="updates" label="Email me about new releases" />
  )
}
```

## 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

- [Switch](https://wunderui.com/components/switch) for a setting that takes effect at once, without a Save button
- [Radio Group](https://wunderui.com/components/radio-group) for one choice out of several options
- [Checkbox Button Group](https://wunderui.com/components/checkbox-button-group) for a multi-select that reads as a row of buttons
- [Selector Item](https://wunderui.com/components/selector-item) for a whole row with a title, a description and a checkbox

## Keyboard

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

| Key | Action |
|---|---|
| `Tab` or `Shift+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 `onCheckedChange`. A box that is `indeterminate` stays a dash until you clear the prop. |

## Behavior

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

- `Checkbox`: 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.
- `Check indicator`: The check, or a dash while indeterminate. Its stroke is drawn in when the box is ticked, and Checkbox renders it for you.
- `Label`: 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.
- `Error message`: 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.
- `CheckboxField`
- `Checkbox`

## Best practices

### When to use

- Use a Checkbox for an on or off choice in a form, or to pick several items from a list. For a setting that takes effect at once use Switch, and for one choice out of several use Radio Group.

### 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.
- Write the label as the choice itself, like Email me about new releases. Put a sentence of detail in the description under it.
- 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.
- 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.
- 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 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 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 offer indeterminate as a choice. It only displays a partial selection, and people can never pick it.
- 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

| Prop | Type | Default | Description |
|---|---|---|---|
| appearance | "brand" \| "neutral" |  | `brand` fills the ticked box with the brand colour; `neutral` fills it with the inverse surface, black in light mode and white in dark mode. |
| checked | boolean | undefined | Whether the box is ticked. Pass it together with `onCheckedChange` to control the box; use `defaultChecked` to let the box keep the value. |
| className | string \| ((state: 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 `mt-0.5`, not to recolour the box. |
| defaultChecked | boolean | false | Whether the box starts ticked, when the box keeps its own value. |
| description | React.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. |
| disabled | boolean | false | The box ignores clicks and keys, is dimmed to 40 % and is skipped by Tab. |
| error | React.ReactNode |  | The message under the row in the error colour. Sets `aria-invalid` on the box, turns its border red and is linked with `aria-describedby`. It sits outside the label. |
| form | string |  | The id of the form that owns the hidden input, for a box that is rendered outside the form. |
| id | string |  | The id of the hidden input. With `label` it joins the label to the box (from `useId` unless you give one); otherwise point the `htmlFor` of a `Label` at it. |
| indeterminate | boolean | false | Shows a dash instead of the check and sets `aria-checked="mixed"`. Use it on a select-all box while only some rows are chosen. It wins over `checked` until you clear it. |
| inputRef | React.Ref<HTMLInputElement> |  | A ref to the hidden `<input>`. The component also copies `aria-label` and `aria-labelledby` onto it. |
| label | React.ReactNode |  | The visible name of the box, to its right. Joined to the box with `htmlFor` in one `<label>`. Any of `label`, `description`, `error` and `wrapperClassName` makes Checkbox render the row instead of the bare box. |
| name | string | undefined | The name of the field when a form is sent. |
| nativeButton | boolean | false | Set it to `true` when `render` swaps the element for a native `<button>`. |
| onCheckedChange | (checked: boolean, eventDetails) => void |  | Called when the box is ticked or unticked, with the new value as a boolean. |
| 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 `checked` and `indeterminate` from your rows, as the Select all example does. |
| readOnly | boolean | false | The box keeps its value and cannot be ticked or unticked. It is announced as read-only. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the box with another tag or component. Accepts an element or a function that returns one. |
| 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 `error` to show the message. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline style for the box, an object or a function of the state. |
| 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. |
| value | string |  | The value sent with the form when the box is ticked. The default is `on`. |
| wrapperClassName | string |  | Class names for the row (or, with `error`, for the wrapper around the row and the message). `className` still goes to the box. |

Also accepts React.HTMLAttributes attributes.

### CheckboxField

| Prop | Type | Default | Description |
|---|---|---|---|
| label* | React.ReactNode |  |  |
| appearance | "brand" \| "neutral" |  | `brand` fills the checked box with the brand colour; `neutral` fills it with the inverse (black/white) surface. |
| checked | boolean | undefined | Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead. |
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| defaultChecked | boolean | false | Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead. |
| description | React.ReactNode |  | A second line under the label in the tertiary colour. |
| disabled | boolean | false | Whether the component should ignore user interaction. |
| error | React.ReactNode |  | Error message under the row. Sets `aria-invalid` and `aria-describedby` 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 | React.Ref<HTMLInputElement> |  | A ref to access the hidden `<input>` element. |
| name | string | undefined | Identifies the field when a form is submitted. |
| nativeButton | boolean | false | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| onCheckedChange | ((checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => 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](https://base-ui.com/react/components/checkbox-group). |
| readOnly | boolean | false | Whether the user should be unable to tick or untick the checkbox. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| required | boolean | false | Whether the user must tick the checkbox before submitting a form. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| 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](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the… |
| wrapperClassName | string |  | Class names for the row (or, with `error`, for the wrapper around the row and the message). |

Also accepts React.HTMLAttributes attributes.

## Examples

### Values: unchecked, checked and indeterminate

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

export function Example() {
  return (
    <Checkbox id="updates" label="Email me about new releases" />
  )
}
```

### Appearance: brand and neutral

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

export function Example() {
  return (
    <Checkbox id="updates" label="Email me about new releases" defaultChecked />
  )
}
```

### States: default and disabled

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

export function Example() {
  return (
    <Checkbox id="remember" label="Remember me on this device" />
  )
}
```

### Label and description: text, hint and row

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

export function Example() {
  return (
    <Checkbox id="remember" label="Remember me on this device" />
  )
}
```

### Error and invalid: a required confirmation

```tsx
import { useState } from "react"
import { Checkbox } from "@/components/ui/checkbox"

export function Example() {
  const [accepted, setAccepted] = useState(false)

  return (
    <Checkbox
      id="terms"
      label="I agree to the Terms of Service and Privacy Policy."
      checked={accepted}
      onCheckedChange={setAccepted}
      aria-invalid={!accepted}
    />
  )
}
```

## In context

### Topics: a group with a rule

The group states its rule up front. With one topic chosen the rule is not met, so the unchecked boxes are invalid and one message sits under the group.

```tsx
import { useState } from "react"
import { Checkbox } from "@/components/ui/checkbox"
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"
import { SelectorItem, SelectorItemGroup } from "@/components/ui/selector-item"

const TOPICS = [
  { id: "updates", title: "Product updates", description: "New features and release highlights" },
  { id: "tips", title: "Design tips", description: "Short guides for building with WunderUI" },
  { id: "notes", title: "Release notes", description: "One email for every version" },
]

export function Example() {
  const [picked, setPicked] = useState<string[]>(["updates"])
  const invalid = picked.length < 2

  return (
    <Fieldset className="min-w-0 gap-3 border-0 bg-transparent p-0" aria-describedby="topics-hint">
      <FieldsetLegend className="mb-1">Topics</FieldsetLegend>
      <p id="topics-hint" className="text-sm text-text-secondary">
        Pick the emails you want to receive.
      </p>
      <SelectorItemGroup>
        {TOPICS.map((topic) => {
          const on = picked.includes(topic.id)
          return (
            <SelectorItem
              key={topic.id}
              controlPosition="leading"
              title={topic.title}
              description={topic.description}
              control={
                <Checkbox
                  checked={on}
                  aria-invalid={invalid && !on}
                  onCheckedChange={(checked) =>
                    setPicked((list) => (checked ? [...list, topic.id] : list.filter((id) => id !== topic.id)))
                  }
                />
              }
            />
          )
        })}
      </SelectorItemGroup>
      {/* The rule is not met, so the message belongs to the group and not to one row. */}
      <div aria-live="polite">
        {invalid && <p className="text-sm text-text-error">Choose at least two topics.</p>}
      </div>
    </Fieldset>
  )
}
```

### Select all: an indeterminate header

The header box shows a dash while only some rows are chosen. It states its scope: it acts on the five visible rows only.

```tsx
import { useState } from "react"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Checkbox } from "@/components/ui/checkbox"
import { Separator } from "@/components/ui/separator"

const MEMBERS = [
  { id: "nora", name: "Nora Lindgren", role: "Product lead", initials: "NL", color: "indigo" },
  { id: "daniel", name: "Daniel Okafor", role: "Engineering", initials: "DO", color: "purple" },
  { id: "priya", name: "Priya Raman", role: "Billing", initials: "PR", color: "pink" },
  { id: "tomas", name: "Tomás Ferreira", role: "Design", initials: "TF", color: "green" },
  { id: "maya", name: "Maya Kessler", role: "Research", initials: "MK", color: "orange" },
] as const

const ROW =
  "flex items-center gap-3 rounded-md px-2 hover:bg-bg-page active:bg-bg-subtle"

export function Example() {
  const [picked, setPicked] = useState<string[]>(["nora", "priya"])
  const all = picked.length === MEMBERS.length
  const some = picked.length > 0 && !all

  return (
    <div className="rounded-xl border border-border bg-card p-2">
      <label className={`${ROW} h-11`}>
        <Checkbox
          aria-label="Select all members"
          checked={all}
          indeterminate={some}
          onCheckedChange={(checked) => setPicked(checked ? MEMBERS.map((member) => member.id) : [])}
        />
        <span className="text-sm font-medium">Select all</span>
        <span className="ml-auto text-xs text-text-secondary">
          {picked.length} of {MEMBERS.length}
        </span>
      </label>
      <Separator className="my-1" />
      {MEMBERS.map((member) => (
        <label key={member.id} className={`${ROW} h-12`}>
          <Checkbox
            aria-label={`Select ${member.name}`}
            checked={picked.includes(member.id)}
            onCheckedChange={(checked) =>
              setPicked((list) => (checked ? [...list, member.id] : list.filter((id) => id !== member.id)))
            }
          />
          <Avatar size="xs" color={member.color} aria-hidden>
            <AvatarFallback>{member.initials}</AvatarFallback>
          </Avatar>
          <span className="flex min-w-0 flex-col">
            <span className="truncate text-sm font-medium">{member.name}</span>
            <span className="truncate text-xs text-text-secondary">{member.role}</span>
          </span>
        </label>
      ))}
      <p className="px-2 pt-2 pb-1 text-xs text-text-secondary">
        Select all acts on the {MEMBERS.length} members shown. Filtered members are not included.
      </p>
    </div>
  )
}
```

### Terms: a single required confirmation

A single required checkbox shows its error on the confirmation itself, after the first try to continue.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"

export function Example() {
  const [accepted, setAccepted] = useState(false)
  const [tried, setTried] = useState(false)
  const [created, setCreated] = useState(false)
  const invalid = tried && !accepted

  return (
    <div className="flex flex-col gap-4">
      {/* The error sits on the confirmation itself: error renders it under the row and wires aria-describedby. */}
      <Checkbox
        id="terms"
        label="I agree to the Terms of Service and Privacy Policy."
        checked={accepted}
        onCheckedChange={setAccepted}
        required
        error={invalid ? "Accept the terms to create your account." : undefined}
      />
      <Button
        variant="gradient"
        onClick={() => {
          setTried(true)
          setCreated(accepted)
        }}
      >
        Create account
      </Button>
      <p aria-live="polite" className="min-h-5 text-sm text-text-secondary">
        {created ? "Account created for info@wunderui.com." : ""}
      </p>
    </div>
  )
}
```

## For AI agents

`get_component("checkbox")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
