Checkbox

A control that lets the user toggle between checked and not checked.

The policy covers how lab data is stored.
import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"
import { HStack, VStack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"
import { widths } from "@/theme/widths"

export default function CheckboxDemo() {
  return (
    <VStack gap={6} xstyle={widths.sm}>
      <HStack gap={2} align="center">
        <Checkbox id="terms-checkbox" name="terms-checkbox" />
        <Label htmlFor="terms-checkbox">Agree to the usage policy</Label>
      </HStack>
      <HStack gap={2} align="start">
        <Checkbox id="terms-checkbox-2" name="terms-checkbox-2" defaultChecked />
        <VStack gap={1}>
          <Label htmlFor="terms-checkbox-2">Agree to the usage policy</Label>
          <Text size="sm" tone="muted" weight="normal">
            The policy covers how lab data is stored.
          </Text>
        </VStack>
      </HStack>
      <HStack gap={2} align="center">
        <Checkbox id="toggle-checkbox" name="toggle-checkbox" disabled />
        <Label htmlFor="toggle-checkbox" disabled>
          Send weekly summaries
        </Label>
      </HStack>
      <Label>
        <Checkbox name="toggle-checkbox-2" />
        <VStack gap={1}>
          <span>Send weekly summaries</span>
          <Text size="sm" tone="muted" weight="normal">
            A short digest of the week&apos;s runs, sent on Mondays.
          </Text>
        </VStack>
      </Label>
    </VStack>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/checkbox

Needs the arene setup first.

Usage

import { Checkbox } from "@/components/ui/checkbox"
<Checkbox id="terms" />
<Label htmlFor="terms">Agree to the usage policy</Label>

Lay a checkbox and its label out in an HStack, or in a horizontal Field for automatic label association.

Checked state

Use defaultChecked for an uncontrolled checkbox, or checked and onCheckedChange to control it.

import { useState } from "react"

export function Example() {
  const [checked, setChecked] = useState(false)

  return <Checkbox checked={checked} onCheckedChange={setChecked} />
}

Invalid state

Set invalid on Field or aria-invalid on a bare checkbox. Both show the destructive border and ring.

import { Checkbox } from "@/components/ui/checkbox"
import { Field, FieldLabel, FieldError } from "@/components/ui/field"
import { Label } from "@/components/ui/label"
import { VStack } from "@/components/ui/stack"

export default function CheckboxInvalid() {
  return (
    <VStack gap={5} width="100%" maxWidth="24rem">
      <VStack gap={2}>
        <Label htmlFor="checkbox-invalid-bare">Agree to the usage policy</Label>
        <Checkbox
          id="checkbox-invalid-bare"
          aria-invalid
          aria-describedby="checkbox-invalid-bare-error"
        />
        <FieldError id="checkbox-invalid-bare-error">
          Agree to the usage policy to continue.
        </FieldError>
      </VStack>
      <Field invalid>
        <FieldLabel>Agree to the usage policy</FieldLabel>
        <Checkbox />
        <FieldError>Agree to the usage policy to continue.</FieldError>
      </Field>
    </VStack>
  )
}

Basic

Pair the checkbox with a Label in an HStack.

import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"
import { HStack } from "@/components/ui/stack"

export default function CheckboxBasic() {
  return (
    <HStack gap={2} align="center">
      <Checkbox id="terms-checkbox-basic" name="terms-checkbox-basic" />
      <Label htmlFor="terms-checkbox-basic">Agree to the usage policy</Label>
    </HStack>
  )
}

Description

Stack the label and a line of helper text in a VStack beside the checkbox, and align the row to start so the box sits on the first line.

The policy covers how lab data is stored, shared and deleted.
import * as stylex from "@stylexjs/stylex"
import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"
import { HStack, VStack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"

const styles = stylex.create({
  field: { width: "100%", maxWidth: "18rem" },
})

export default function CheckboxDescription() {
  return (
    <HStack gap={2} align="start" xstyle={styles.field}>
      <Checkbox id="terms-checkbox-desc" name="terms-checkbox-desc" defaultChecked />
      <VStack gap={1}>
        <Label htmlFor="terms-checkbox-desc">Agree to the usage policy</Label>
        <Text size="sm" tone="muted">
          The policy covers how lab data is stored, shared and deleted.
        </Text>
      </VStack>
    </HStack>
  )
}

Disabled

Set disabled on Field to disable its control and dim its label, or on a bare control directly.

import { Checkbox } from "@/components/ui/checkbox"
import { Field, FieldLabel } from "@/components/ui/field"
export default function CheckboxDisabled() {
  return (
    <Field orientation="horizontal" disabled>
      <Checkbox name="notifications" />
      <FieldLabel>Send weekly summaries</FieldLabel>
    </Field>
  )
}

Group

Use Checkbox Group to share selection state and Field validation.

Include in the export:

Choose what goes into the exported notebook.

import { Checkbox } from "@/components/ui/checkbox"
import { CheckboxGroup } from "@/components/ui/checkbox-group"
import { Field, FieldDescription, FieldItem, FieldLabel } from "@/components/ui/field"
const items = [
  { value: "raw-data", label: "Raw data" },
  { value: "plots", label: "Plots" },
  { value: "lab-notes", label: "Lab notes" },
  { value: "instrument-logs", label: "Instrument logs" },
]
export default function CheckboxGroupExample() {
  return (
    <Field name="export-items">
      <FieldLabel nativeLabel={false} render={<div />}>
        Include in the export:
      </FieldLabel>
      <FieldDescription>Choose what goes into the exported notebook.</FieldDescription>
      <CheckboxGroup defaultValue={["raw-data", "plots"]}>
        {items.map(({ value, label }) => (
          <FieldItem key={value}>
            <FieldLabel>
              <Checkbox value={value} />
              {label}
            </FieldLabel>
          </FieldItem>
        ))}
      </CheckboxGroup>
    </Field>
  )
}

Indeterminate

Use parent inside a controlled Checkbox Group with allValues to derive the checked and indeterminate states automatically.

Use the indeterminate prop for a parent that controls a set of children. It draws a dash in place of the tick and is independent of checked.

"use client"

import { useState } from "react"
import * as stylex from "@stylexjs/stylex"
import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"
import { HStack, VStack } from "@/components/ui/stack"
import { space } from "@/theme/tokens.stylex"

const styles = stylex.create({
  children: { paddingInlineStart: space.s6 },
})

const permissions = [
  { id: "read", label: "Read" },
  { id: "write", label: "Write" },
  { id: "deploy", label: "Deploy" },
]

export default function CheckboxIndeterminate() {
  const [granted, setGranted] = useState<string[]>(["read"])

  const all = granted.length === permissions.length
  const some = granted.length > 0 && !all

  return (
    <VStack gap={3}>
      <HStack gap={2} align="center">
        <Checkbox
          id="permissions-all"
          checked={all}
          indeterminate={some}
          onCheckedChange={(checked) => setGranted(checked ? permissions.map((p) => p.id) : [])}
        />
        <Label htmlFor="permissions-all">All permissions</Label>
      </HStack>
      <VStack gap={3} xstyle={styles.children}>
        {permissions.map((permission) => (
          <HStack key={permission.id} gap={2} align="center">
            <Checkbox
              id={`permissions-${permission.id}`}
              checked={granted.includes(permission.id)}
              onCheckedChange={(checked) =>
                setGranted((current) =>
                  checked
                    ? [...current, permission.id]
                    : current.filter((id) => id !== permission.id),
                )
              }
            />
            <Label htmlFor={`permissions-${permission.id}`}>{permission.label}</Label>
          </HStack>
        ))}
      </VStack>
    </VStack>
  )
}

indeterminate is a display state. Clicking the checkbox still fires onCheckedChange with the opposite of checked, so decide what a click on a mixed parent means and set checked from that.

API reference

Pass render to replace a part's element or compose it with another component.

Checkbox wraps the Base UI Checkbox.Root and renders its Indicator inside. See the Base UI reference for the full list of props.

Checkbox

PropTypeDefault
checkedboolean—
defaultCheckedbooleanfalse
onCheckedChange(checked: boolean, details) => void—
indeterminatebooleanfalse
disabledbooleanfalse
readOnlybooleanfalse
requiredbooleanfalse
namestring—
valuestring—
idstring—
inputRefRef<HTMLInputElement>—
xstyleStyleXStyles—
styleCSSProperties—
classNamestring—

The root is a <span role="checkbox">. Base UI renders a hidden <input> beside it that carries id, name and value. A label's htmlFor and a form submission reach the control through that input.

checkboxStyles

The style maps behind the component. Spread them onto any element.

KeyWhat it is
rootThe box: size, border width, corner, hit area
indicatorThe tick's box and its fade
indicatorHiddenThe tick faded out and scaled down
choiceThe hairline edge and fill at a choice's size
checkedThe flat primary fill and inverted tick colour
disabledThe dimmed, non-interactive state
invalidThe destructive border and ring

root carries no colour and no focus ring. Everything else comes from states in theme/states.ts. Merge choice, then states.focusRing. Merge invalid before checked, so a ticked invalid box keeps the primary fill and shows only the destructive ring.

Data attributes

AttributeOnEffect
data-slot="checkbox"the rootTargets the box from a parent
data-slot="checkbox-indicator"the indicatorTargets the animated indicator
data-checked, data-uncheckedroot, indicatorBase UI writes them
data-parentrootControls the group selection
data-indeterminateroot, indicatorBase UI writes it
data-disabled, data-readonly, data-requiredroot, indicatorBase UI writes them
data-starting-style, data-ending-stylethe indicatorBase UI writes them while the tick enters or leaves