Checkbox

Email me about product updates

import { Checkbox } from "@/components/ui/checkbox";

export default function CheckboxDemo() {
  return <Checkbox defaultSelected>Email me about product updates</Checkbox>;
}

Installation

$ pnpm dlx shadcn@latest add @desyne/checkbox

The CLI installs dependencies and any other components this one uses.

Usage

tsx

import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

tsx

<Checkbox>Remember me</Checkbox>

<CheckboxGroup label="Notify me about" defaultValue={["mentions"]}>
  <Checkbox value="mentions">Mentions</Checkbox>
  <Checkbox value="comments">Comments</Checkbox>
</CheckboxGroup>

A standalone Checkbox owns a boolean (isSelected). Inside a CheckboxGroup, each checkbox needs a value and the group owns a string[] of the selected values.

When to use

Checkbox — independent options, any number of which can be on, usually confirmed with a submit button.
Switch — a single setting that takes effect immediately, like turning on dark mode.
Radio Group — exactly one choice from a small, visible set.
Toggle Button Group — compact multi-select inside toolbars.
List Box or Tag Group — multi-select from a long or dynamic list.

Anatomy

Checkbox is built on React Aria's CheckboxField and CheckboxButton. You only render Checkbox; it composes the parts for you:

tsx

<CheckboxGroup>                  {/* label, description, error message */}
  <Checkbox value="…">           {/* CheckboxField: <div>, owns state and validation */}
    {/* CheckboxButton: <label> wrapping a hidden <input type="checkbox"> */}
    {/*   box + children + description (Text slot="description") */}
    {/* FieldError: standalone checkboxes only */}
  </Checkbox>
</CheckboxGroup>

Part	Renders	Notes
`Checkbox` root (`CheckboxField`)	`<div data-slot="checkbox-field">`	Holds the checked state, `name` / `value`, validation and the ARIA wiring between the input, description and error. Carries `data-selected`, `data-indeterminate`, `data-disabled`, `data-readonly`, `data-invalid`, `data-required`.
`CheckboxButton`	`<label data-slot="checkbox">` + hidden `<input type="checkbox">`	The clickable area: box, label and description. Receives `className`, `style`, `render`, `children` and hover handlers, and carries every interaction attribute.
Box	`<span data-slot="checkbox-indicator">`	Shows a check icon, or a minus icon when `isIndeterminate`. Sized by `size`.
Description	`<span slot="description">`	From the `description` prop. Rendered inside the label so the whole area stays clickable, and linked to the input with `aria-describedby`.
`FieldError`	`<div data-slot="field-error">`	Standalone checkboxes only: shows `errorMessage` or the browser message when validation fails. Inside a group, the group shows one error instead.
`CheckboxGroup`	`<div role="group">`	Wraps the label, description, the checkboxes and the error message.
Group label / description	`<span>`	Rendered from the group's `label` and `description` props.

Checked, unchecked and indeterminate are the three visual values. isInvalid turns the box red, isDisabled dims it and removes it from the tab order, and isReadOnly keeps it focusable but ignores changes.

import { Checkbox } from "@/components/ui/checkbox";

export default function CheckboxStates() {
  return (
    <div className="grid grid-cols-2 gap-x-8 gap-y-4">
      <Checkbox>Unchecked</Checkbox>
      <Checkbox defaultSelected>Checked</Checkbox>
      <Checkbox isIndeterminate>Indeterminate</Checkbox>
      <Checkbox isInvalid>Invalid</Checkbox>
      <Checkbox isDisabled>Disabled</Checkbox>
      <Checkbox isDisabled defaultSelected>
        Disabled checked
      </Checkbox>
      <Checkbox isReadOnly defaultSelected>
        Read-only
      </Checkbox>
      <Checkbox isInvalid defaultSelected>
        Invalid checked
      </Checkbox>
    </div>
  );
}

Sizes

md (16px) is the default. sm fits dense tables and filters; lg also bumps the label to text-base for touch-first layouts.

Small

Medium

Large

import { Checkbox } from "@/components/ui/checkbox";

export default function CheckboxSizes() {
  return (
    <div className="flex items-center gap-6">
      <Checkbox size="sm" defaultSelected>
        Small
      </Checkbox>
      <Checkbox size="md" defaultSelected>
        Medium
      </Checkbox>
      <Checkbox size="lg" defaultSelected>
        Large
      </Checkbox>
    </div>
  );
}

With description

description adds secondary text under the label and aligns the box to the first line. Use it to explain the consequence of an option instead of a long label.

Email notifications

import { Checkbox } from "@/components/ui/checkbox";

export default function CheckboxDescription() {
  return (
    <Checkbox
      className="max-w-xs"
      defaultSelected
      description="Get a weekly digest of activity in your workspace."
    >
      Email notifications
    </Checkbox>
  );
}

Controlled

Use isSelected and onChange to own the value, for example to show or persist it elsewhere. Use defaultSelected when you only need the initial value.

Enable two-factor authentication

Two-factor is off.

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

export default function CheckboxControlled() {
  const [isSelected, setSelected] = useState(false);
  return (
    <div className="flex flex-col items-start gap-3">
      <Checkbox isSelected={isSelected} onChange={setSelected}>
        Enable two-factor authentication
      </Checkbox>
      <p className="text-muted-foreground text-sm">
        Two-factor is{" "}
        <span className="font-medium text-foreground">
          {isSelected ? "on" : "off"}
        </span>
        .
      </p>
    </div>
  );
}

Group

CheckboxGroup renders a shared label and description, gives the checkboxes role="group", and collects the selected values into an array.

Notify me aboutWe'll only email you about the things you pick.

Mentions

Replies to my comments

Issues assigned to me

Product updates

import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function CheckboxGroupDemo() {
  return (
    <CheckboxGroup
      label="Notify me about"
      description="We'll only email you about the things you pick."
      defaultValue={["mentions", "comments"]}
    >
      <Checkbox value="mentions">Mentions</Checkbox>
      <Checkbox value="comments">Replies to my comments</Checkbox>
      <Checkbox value="assigned">Issues assigned to me</Checkbox>
      <Checkbox value="updates">Product updates</Checkbox>
    </CheckboxGroup>
  );
}

Horizontal

orientation="horizontal" lays the checkboxes out in a wrapping row. Keep labels short; switch back to vertical as soon as options wrap to a second line.

Platforms

Web

iOS

Android

Desktop

import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function CheckboxHorizontal() {
  return (
    <CheckboxGroup
      label="Platforms"
      orientation="horizontal"
      defaultValue={["web", "ios"]}
    >
      <Checkbox value="web">Web</Checkbox>
      <Checkbox value="ios">iOS</Checkbox>
      <Checkbox value="android">Android</Checkbox>
      <Checkbox value="desktop">Desktop</Checkbox>
    </CheckboxGroup>
  );
}

Disabled and read-only in a group

isDisabled on a single checkbox locks just that option; use the description to say why. isReadOnly on the group shows the current value without letting users change it, and keeps every option focusable.

import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function CheckboxGroupDisabled() {
  return (
    <div className="flex flex-col gap-8">
      <CheckboxGroup
        label="Email alerts"
        description="Security alerts are required by your organization."
        defaultValue={["security", "billing"]}
      >
        <Checkbox value="security" isDisabled>
          Security alerts
        </Checkbox>
        <Checkbox value="billing">Billing and invoices</Checkbox>
        <Checkbox value="digest">Weekly digest</Checkbox>
      </CheckboxGroup>
      <CheckboxGroup
        label="Included in your plan"
        isReadOnly
        defaultValue={["sso", "audit"]}
      >
        <Checkbox value="sso">Single sign-on</Checkbox>
        <Checkbox value="audit">Audit log</Checkbox>
        <Checkbox value="scim">SCIM provisioning</Checkbox>
      </CheckboxGroup>
    </div>
  );
}

Controlled group

Pass value and onChange to the group to own the array of selected values.

Languages

TypeScript

Python

Rust

Selected: typescript

import { useState } from "react";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function CheckboxGroupControlled() {
  const [value, setValue] = useState<string[]>(["typescript"]);
  return (
    <div className="flex flex-col gap-4">
      <CheckboxGroup label="Languages" value={value} onChange={setValue}>
        <Checkbox value="typescript">TypeScript</Checkbox>
        <Checkbox value="python">Python</Checkbox>
        <Checkbox value="go">Go</Checkbox>
        <Checkbox value="rust">Rust</Checkbox>
      </CheckboxGroup>
      <p className="text-muted-foreground text-sm">
        Selected:{" "}
        <span className="font-medium text-foreground">
          {value.length ? value.join(", ") : "none"}
        </span>
      </p>
    </div>
  );
}

Indeterminate

A parent checkbox for a set of children. Set isIndeterminate when only some children are selected. It's purely visual (announced as "mixed"), so you must control it; pressing the checkbox calls onChange with the next value.

All project permissions

View projects

Edit projects

Delete projects

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

const permissions = [
  { id: "read", label: "View projects" },
  { id: "write", label: "Edit projects" },
  { id: "delete", label: "Delete projects" },
];

export default function CheckboxIndeterminate() {
  const [selected, setSelected] = useState<string[]>(["read"]);
  const all = selected.length === permissions.length;
  return (
    <div className="flex flex-col gap-3">
      <Checkbox
        isSelected={all}
        isIndeterminate={selected.length > 0 && !all}
        onChange={(checked) =>
          setSelected(checked ? permissions.map((p) => p.id) : [])
        }
      >
        All project permissions
      </Checkbox>
      <div className="flex flex-col gap-3 border-l pl-5">
        {permissions.map((p) => (
          <Checkbox
            key={p.id}
            isSelected={selected.includes(p.id)}
            onChange={(checked) =>
              setSelected((s) =>
                checked ? [...s, p.id] : s.filter((id) => id !== p.id),
              )
            }
          >
            {p.label}
          </Checkbox>
        ))}
      </div>
    </div>
  );
}

Cards

className is merged with the base styles, so a border, padding and data-selected: styles turn a checkbox with a description into a selectable card. The whole card is the label, so it's all clickable.

Add-ons

Daily backups

Global CDN

Priority support

import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

const addons = [
  {
    id: "backups",
    title: "Daily backups",
    description: "Point-in-time restore for the last 30 days. $10/mo",
  },
  {
    id: "cdn",
    title: "Global CDN",
    description: "Serve assets from 300+ edge locations. $15/mo",
  },
  {
    id: "support",
    title: "Priority support",
    description: "4-hour response time, 24/7. $49/mo",
  },
];

export default function CheckboxCards() {
  return (
    <CheckboxGroup
      label="Add-ons"
      defaultValue={["backups"]}
      className="w-full max-w-sm"
    >
      {addons.map((addon) => (
        <Checkbox
          key={addon.id}
          value={addon.id}
          description={addon.description}
          className="w-full rounded-lg border bg-card p-3.5 shadow-xs transition-[border-color,background-color] data-hovered:border-brand/50 data-selected:border-brand data-selected:bg-brand/[0.04] data-focus-visible:ring-[3px] data-focus-visible:ring-ring/25"
        >
          {addon.title}
        </Checkbox>
      ))}
    </CheckboxGroup>
  );
}

Required and validation

isRequired on a group requires at least one selection; on a standalone checkbox it requires it to be checked. With the default native validation, submitting the form shows the errorMessage (or the browser message) under the group or the standalone checkbox and focuses the first invalid field. A required group also adds a * to its label.

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function CheckboxValidation() {
  return (
    <Form
      className="flex w-full max-w-xs flex-col gap-5"
      onSubmit={(e) => e.preventDefault()}
    >
      <CheckboxGroup
        label="How did you hear about us?"
        isRequired
        errorMessage="Pick at least one option."
      >
        <Checkbox value="search">Search engine</Checkbox>
        <Checkbox value="friend">A friend or colleague</Checkbox>
        <Checkbox value="social">Social media</Checkbox>
      </CheckboxGroup>
      <Checkbox isRequired>I agree to the Terms of Service</Checkbox>
      <Button type="submit" className="self-start">
        Continue
      </Button>
    </Form>
  );
}

Custom validation

validate receives the selected values and returns an error string, or null when valid. With validationBehavior="aria" the error shows as soon as the value changes instead of on submit.

import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

const topics = [
  "Design systems",
  "Accessibility",
  "Performance",
  "Testing",
  "Animation",
];

export default function CheckboxCustomValidation() {
  return (
    <CheckboxGroup
      label="Topics to follow"
      description="Choose up to three."
      defaultValue={["Accessibility"]}
      validationBehavior="aria"
      validate={(value) =>
        value.length > 3 ? "You can follow up to three topics." : null
      }
    >
      {topics.map((topic) => (
        <Checkbox key={topic} value={topic}>
          {topic}
        </Checkbox>
      ))}
    </CheckboxGroup>
  );
}

Form submission

Give the group a name and every checked value is submitted under it; read them with FormData.getAll(). A standalone checkbox submits its value ("on" by default) only when checked.

import { useState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function CheckboxForm() {
  const [result, setResult] = useState<string | null>(null);
  return (
    <Form
      className="flex w-full max-w-xs flex-col gap-5"
      onSubmit={(e) => {
        e.preventDefault();
        const data = new FormData(e.currentTarget);
        setResult(
          JSON.stringify({
            toppings: data.getAll("toppings"),
            extraNapkins: data.get("napkins"),
          }),
        );
      }}
    >
      <CheckboxGroup label="Toppings" name="toppings" defaultValue={["cheese"]}>
        <Checkbox value="cheese">Extra cheese</Checkbox>
        <Checkbox value="mushrooms">Mushrooms</Checkbox>
        <Checkbox value="olives">Olives</Checkbox>
      </CheckboxGroup>
      <Checkbox name="napkins" value="yes">
        Extra napkins
      </Checkbox>
      <Button type="submit" className="self-start">
        Place order
      </Button>
      {result && (
        <code className="rounded-md bg-muted px-2 py-1 text-xs">{result}</code>
      )}
    </Form>
  );
}

Recipes

Bulk selection

A select-all checkbox in a list header, indeterminate while only some rows are selected, with bulk actions that appear once anything is selected. Row checkboxes have no visible label, so each gets an aria-label.

import { ArchiveIcon, FileTextIcon, Trash2Icon } from "lucide-react";
import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Checkbox } from "@/components/ui/checkbox";

const files = [
  { id: "q3-report", name: "Q3 revenue report.pdf", size: "2.4 MB" },
  { id: "roadmap", name: "2025 roadmap.key", size: "18.1 MB" },
  { id: "brand", name: "Brand guidelines.fig", size: "7.8 MB" },
  { id: "contract", name: "Vendor contract (signed).pdf", size: "312 KB" },
];

export default function CheckboxRecipeBulkSelect() {
  const [selected, setSelected] = useState<Set<string>>(new Set(["roadmap"]));
  const all = selected.size === files.length;
  const toggle = (id: string, checked: boolean) =>
    setSelected((s) => {
      const next = new Set(s);
      if (checked) next.add(id);
      else next.delete(id);
      return next;
    });

  return (
    <div className="w-full max-w-md overflow-hidden rounded-xl border bg-card">
      <div className="flex h-12 items-center justify-between gap-3 border-b bg-muted/40 px-4">
        <Checkbox
          isSelected={all}
          isIndeterminate={selected.size > 0 && !all}
          onChange={(checked) =>
            setSelected(checked ? new Set(files.map((f) => f.id)) : new Set())
          }
        >
          {selected.size > 0 ? `${selected.size} selected` : "Select all"}
        </Checkbox>
        {selected.size > 0 && (
          <div className="flex gap-1">
            <Button variant="ghost" size="sm">
              <ArchiveIcon /> Archive
            </Button>
            <Button variant="ghost" color="danger" size="sm">
              <Trash2Icon /> Delete
            </Button>
          </div>
        )}
      </div>
      <ul className="divide-y">
        {files.map((file) => (
          <li key={file.id} className="flex items-center gap-3 px-4 py-3">
            <Checkbox
              aria-label={`Select ${file.name}`}
              isSelected={selected.has(file.id)}
              onChange={(checked) => toggle(file.id, checked)}
            />
            <FileTextIcon className="size-4 shrink-0 text-muted-foreground" />
            <span className="min-w-0 flex-1 truncate text-sm">{file.name}</span>
            <span className="text-muted-foreground text-xs tabular-nums">
              {file.size}
            </span>
          </li>
        ))}
      </ul>
    </div>
  );
}

Notification matrix

A table of events × channels. Each checkbox gets an aria-label combining its row and column, since the visual headers aren't associated with it.

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

const channels = [
  { id: "email", label: "Email" },
  { id: "push", label: "Push" },
  { id: "sms", label: "SMS" },
] as const;

const events = [
  { id: "mention", label: "Someone mentions you" },
  { id: "assign", label: "An issue is assigned to you" },
  { id: "deploy", label: "A deploy fails" },
  { id: "invoice", label: "A new invoice is available" },
];

type Channel = (typeof channels)[number]["id"];

export default function CheckboxRecipeNotificationMatrix() {
  const [prefs, setPrefs] = useState<Record<string, Channel[]>>({
    mention: ["email", "push"],
    assign: ["email"],
    deploy: ["email", "push", "sms"],
    invoice: ["email"],
  });

  return (
    <div className="w-full max-w-lg overflow-x-auto rounded-xl border bg-card">
      <table className="w-full text-sm">
        <thead>
          <tr className="border-b bg-muted/40 text-muted-foreground text-xs">
            <th className="px-4 py-2.5 text-left font-medium">
              Notify me when
            </th>
            {channels.map((c) => (
              <th key={c.id} className="w-16 px-2 py-2.5 font-medium">
                {c.label}
              </th>
            ))}
          </tr>
        </thead>
        <tbody className="divide-y">
          {events.map((event) => (
            <tr key={event.id}>
              <td className="px-4 py-3">{event.label}</td>
              {channels.map((c) => (
                <td key={c.id} className="px-2 py-3">
                  <div className="flex justify-center">
                    <Checkbox
                      aria-label={`${c.label}: ${event.label}`}
                      isSelected={prefs[event.id].includes(c.id)}
                      isDisabled={c.id === "sms" && event.id !== "deploy"}
                      onChange={(checked) =>
                        setPrefs((p) => ({
                          ...p,
                          [event.id]: checked
                            ? [...p[event.id], c.id]
                            : p[event.id].filter((id) => id !== c.id),
                        }))
                      }
                    />
                  </div>
                </td>
              ))}
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

Onboarding checklist

A controlled group drives a ProgressBar. children is a render function, so completed steps are struck through.

Getting started1 of 4

Complete your profile

Invite your team

Connect a repository

Create your first project

import { useState } from "react";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";
import { ProgressBar } from "@/components/ui/progress-bar";

const steps = [
  {
    id: "profile",
    title: "Complete your profile",
    description: "Add a photo and your job title.",
  },
  {
    id: "invite",
    title: "Invite your team",
    description: "Projects work best with at least two people.",
  },
  {
    id: "repo",
    title: "Connect a repository",
    description: "Import issues from GitHub or GitLab.",
  },
  {
    id: "project",
    title: "Create your first project",
    description: "Start from a template or a blank board.",
  },
];

export default function CheckboxRecipeChecklist() {
  const [done, setDone] = useState<string[]>(["profile"]);
  return (
    <div className="flex w-full max-w-sm flex-col gap-4 rounded-xl border bg-card p-5">
      <ProgressBar
        label="Getting started"
        value={done.length}
        maxValue={steps.length}
        valueLabel={`${done.length} of ${steps.length}`}
        color="success"
      />
      <CheckboxGroup
        aria-label="Onboarding steps"
        value={done}
        onChange={setDone}
      >
        {steps.map((step) => (
          <Checkbox
            key={step.id}
            value={step.id}
            description={step.description}
          >
            {({ isSelected }) => (
              <span
                className={
                  isSelected ? "text-muted-foreground line-through" : undefined
                }
              >
                {step.title}
              </span>
            )}
          </Checkbox>
        ))}
      </CheckboxGroup>
    </div>
  );
}

Accessibility

Each checkbox is a native <input type="checkbox">, visually hidden inside a <label>, so clicking anywhere on the label toggles it and it works with every assistive technology and with native forms.
isIndeterminate sets the input's indeterminate property, which screen readers announce as "mixed".
Checkboxes without visible text (table rows, matrices) need an aria-label or aria-labelledby.
CheckboxGroup renders role="group" labelled by its label; its description and error message are linked with aria-describedby.
description on a Checkbox is linked to the input with aria-describedby, so it's announced as the description rather than as part of the name. It sits inside the <label> (so it's clickable) but is hidden from the name computation.
A standalone checkbox's error message is linked to the input with aria-describedby as well.
The focus ring only appears for keyboard focus (data-focus-visible).

Keyboard

Key	Action
`Tab`	Moves focus to the next checkbox. Every checkbox in a group is its own tab stop.
`Space`	Toggles the focused checkbox

Styling

Data attributes

The attributes you'll style against are on the <label> (CheckboxButton), which is also where className goes. Target the box or label text from it with group-data-*/checkbox:. The outer CheckboxField <div> repeats the state attributes (not the interaction ones) and is a group/checkbox-field, for styling siblings such as the error message.

Attribute	`<label>` (`CheckboxButton`)	`<div>` (`CheckboxField`)	Present when
`data-selected`	Yes	Yes	Checked
`data-indeterminate`	Yes	Yes	`isIndeterminate` is true
`data-hovered`	Yes	No	Hovered with a mouse or pen
`data-pressed`	Yes	No	Being pressed
`data-focused` / `data-focus-visible`	Yes	No	Focused / focused with the keyboard
`data-disabled`	Yes	Yes	Disabled, directly or through the group
`data-readonly`	Yes	Yes	Read-only, directly or through the group
`data-invalid`	Yes	Yes	Invalid, directly or through the group
`data-required`	Yes	Yes	Required

On CheckboxGroup (children can use group-data-*/field:): data-disabled, data-readonly, data-required, data-invalid.

Slots

`data-slot`	Element
`checkbox-field`	Each checkbox's outer `<div>` (`CheckboxField`)
`checkbox`	Each checkbox's `<label>` (`CheckboxButton`), where `className` goes
`checkbox-indicator`	The box
`checkbox-group`	Group root
`label`, `description`, `field-error`	Group label, description and error message; `description` and `field-error` are also used on a standalone checkbox

Color

The box uses the --brand and --brand-foreground theme variables (red --destructive when invalid). Override them on a single checkbox or a whole group for a one-off color:

tsx

<Checkbox className="[--brand:var(--color-emerald-600)] [--brand-foreground:white]">
  Mark as paid
</Checkbox>

Render props

className and children accept a function of the CheckboxButton state (isSelected, isIndeterminate, isHovered, isPressed, isFocusVisible, isDisabled, isReadOnly, isInvalid, isRequired):

tsx

<Checkbox className={({ isSelected }) => (isSelected ? "font-medium" : "")}>
  {({ isIndeterminate }) => (isIndeterminate ? "Some selected" : "Select all")}
</Checkbox>

API Reference

Checkbox

Prop

Type

Also accepts every prop of React Aria's CheckboxField. className, style, render, children and the hover handlers go to the CheckboxButton instead; everything else (state, name, value, validation, focus and press handlers, ARIA and DOM attributes) goes to the CheckboxField.

CheckboxGroup

Prop

Type

Also accepts every prop of React Aria's CheckboxGroup.

Switch — for settings that apply immediately.
Radio Group — for a single choice.
Toggle Button Group — multi-select as buttons.
Table — has built-in row selection with checkboxes.