Skip to content
opsinjs
Edit this page

Components

Checkbox

A single labelled box a reader ticks, unticks or leaves in a mixed state, built on Base UI Checkbox and carrying neither colour axis.

Usage

pnpm dlx shadcn@latest add @opsinjs/checkbox

The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.

import { Checkbox } from "@/components/ui/checkbox"
<Checkbox
  label="Email me a copy"
  checked={agreed}
  onCheckedChange={setAgreed}
/>

Examples

Theme
Density
Text
Status
Accent theme
Accent
checkbox · base base · style base-lyraOpen under the product theme

An optional agreement

A lone box with label and description. The description says what ticking does.

Theme
Density
Text
Status
Accent theme
Accent
checkbox-an-optional-agreement · base base · style base-lyraOpen under the product theme
checkbox-an-optional-agreement.tsx
"use client"

import { useState } from "react"

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

export default function CheckboxAnOptionalAgreement() {
  const [checked, setChecked] = useState(false)
  return (
    <Checkbox
      label="Email me a copy"
      description="We send a copy to the address on your account after you save."
      checked={checked}
      onCheckedChange={setChecked}
    />
  )
}

A three-state parent

The example passes checked="indeterminate" when some but not all children are ticked, so the box draws a Minus, not a Check.

Theme
Density
Text
Status
Accent theme
Accent
checkbox-a-three-state-parent · base base · style base-lyraOpen under the product theme
checkbox-a-three-state-parent.tsx
"use client"

import { useState } from "react"

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

const ITEMS = [
  { id: "notes", label: "Recent notes" },
  { id: "files", label: "Shared files" },
  { id: "reminders", label: "Reminders" },
]

export default function CheckboxAThreeStateParent() {
  const [checkedIds, setCheckedIds] = useState<string[]>(["notes"])

  const allChecked = checkedIds.length === ITEMS.length
  const noneChecked = checkedIds.length === 0
  const parentChecked: boolean | "indeterminate" = allChecked
    ? true
    : noneChecked
      ? false
      : "indeterminate"

  const setParent = (next: boolean) => {
    setCheckedIds(next ? ITEMS.map((item) => item.id) : [])
  }

  const setChild = (id: string, next: boolean) => {
    setCheckedIds((current) =>
      next ? [...current, id] : current.filter((existing) => existing !== id),
    )
  }

  return (
    <div className="flex flex-col gap-opsin-2">
      <Checkbox
        label="Include in export"
        checked={parentChecked}
        onCheckedChange={setParent}
      />
      <div className="flex flex-col gap-opsin-1 ps-opsin-6">
        {ITEMS.map((item) => (
          <Checkbox
            key={item.id}
            label={item.label}
            checked={checkedIds.includes(item.id)}
            onCheckedChange={(next) => setChild(item.id, next)}
          />
        ))}
      </div>
    </div>
  )
}

When to use it

Use it when

  • A single option a reader turns on or off, such as an optional agreement.
  • Any-number-including-none choices across a short list, where each row is its own box.
  • The head of such a list, where a parent box uses the mixed state for the some case.

Do not use it when

  • Exactly one option must be chosen. Checkboxes let a reader pick two answers to a one-answer question.Use radio-group instead.
  • The label has to say what a reading means or how urgent it is.Use status-pill instead.
  • The box has to join a form's label, hint, error and validity as one unit.Use field instead.

Accessibility

The description is tied with aria-describedby, and fill, border and the Check against Minus glyph move together, so colour is never the sole state carrier. Sizes are rem. The tick draws itself along its stroke on spring-snap, which collapses to 0ms under prefers-reduced-motion, so there the tick is whole the frame after the box is ticked. The audit fixed a missing name (WCAG 4.1.2): Base UI draws the box as a span with role="checkbox", and the wrapping label named only the hidden input. The box now points aria-labelledby at the visible label's id, so its name is the visible words verbatim (WCAG 2.5.3), in the demo and both examples.

Residual items.

  • The inner box measures 20 by 20, under SC 2.5.8, but the pointer target is the 44px label row, which toggles anywhere along it and so clears the house floor.
  • Contrast pairs are not yet measured.
KeyActionNotes
TabMoves focus onto the boxOne tab stop. A disabled box is skipped.
Shift+TabMoves focus back off the boxOne stop in reverse too.
SpaceToggles the boxA mixed box becomes ticked and reports true.
EnterDoes nothingA box at the foot of a form does not toggle on submit.
Pointer on the labelToggles the boxAnywhere along the row, not only the box.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor

These are the measured token pairs this component draws colour from, not a measurement of the component itself.

Props interface

Prop

Type

Generated from CheckboxProps in registry/bases/base/checkbox.tsx.

label is required. checked accepts true, false or "indeterminate"; omitted, the box is uncontrolled from an unticked start. indeterminate is the other route to the mixed state and wins when both are given. onCheckedChange reports a boolean, so a mixed box reports true when ticked.

Data attributes

AttributeConditionValue
data-slotOn the root and every inner partcheckbox, checkbox-control, checkbox-indicator, checkbox-label, checkbox-description
data-checkedOn Checkbox.Control while tickedSet by Base UI
data-uncheckedOn Checkbox.Control while neither ticked nor mixedSet by Base UI
data-indeterminateOn Checkbox.Control while mixedSet by Base UI
data-disabledOn Checkbox.Control while disabledSet by Base UI