Skip to content
Tier

Checkbox

Free · MIT

A box that is checked, unchecked or indeterminate, for one choice the person makes.

Markdown
Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0 and 2.2.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Loading the preview

Install

With the Candor CLI
Open the starter in StackBlitz

Opens the free starter app in StackBlitz, in your browser, on stackblitz.com. Checkbox isn’t added for you: run npx candor-ui add checkbox in its terminal. The starter’s agent needs an Anthropic API key to chat; without one it shows the components only.

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/checkbox

Brings in: motion, tokens, utils · npm: @base-ui/react@^1.9.0

Usage

TSX · The example above
"use client"

import * as React from "react"
import { Checkbox } from "@/components/candor/ui/checkbox"
import { Label } from "@/components/candor/ui/label"
import { Locked } from "@/components/candor/locked"

const channels = [
  { id: "email", label: "Email me when a run needs a decision" },
  { id: "digest", label: "Send a weekly summary of finished runs" },
]

export default function Example() {
  // Nothing is ticked until the person ticks it.
  const [ticked, setTicked] = React.useState<string[]>([])
  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      {channels.map((c) => (
        <div key={c.id} className="flex items-center gap-2.5">
          <Checkbox
            id={c.id}
            checked={ticked.includes(c.id)}
            onCheckedChange={(on) => setTicked((t) => (on === true ? [...t, c.id] : t.filter((x) => x !== c.id)))}
          />
          <Label htmlFor={c.id}>{c.label}</Label>
        </div>
      ))}
      <div className="flex items-center gap-2.5">
        <Locked inline reason="Your workspace sets this for everyone.">
          <Checkbox id="audit" />
        </Locked>
        <Label htmlFor="audit">Keep an audit log of changes</Label>
      </div>
    </div>
  )
}

<Checkbox>

PropTypeDefaultDescription
classNamestring | undefined—Classes, merged with Candor's.
checkedCheckedState | undefined—Whether the box is ticked, when the app controls it; `"indeterminate"` shows a dash (some of its children are ticked).
defaultCheckedCheckedState | undefined—Whether the box starts ticked, when the box keeps its own state. Leave it out for a choice the person makes.
onCheckedChange((checked: boolean, details: CheckboxPrimitive.Root.ChangeEventDetails) => void) | undefined—Called with the new state when the person ticks or unticks the box, and Base UI's change details.

Also takes the props of Omit<CheckboxPrimitive.Root.Props, "className" | "checked" | "defaultChecked" | "onCheckedChange" | "indeterminate">.

Motion

MomentFamilyWhat it does
tickmark, drawThe tick draws along its path when the person checks the box. A box that is already checked when it appears, or that the app changes, shows its tick at once: nothing is drawn for a change the person didn't make.

Set with --cd-motion-checkbox-<moment>-* in your brand file; the families are in the design reference.