Checkbox

A binary choice. Backed by Radix UI's checkbox primitive — keyboard navigation, ARIA attributes, and the indeterminate state come for free.

import { Checkbox } from '@dashforge/tw';

<Checkbox label="I agree to the terms" />

Quick Start

Standalone:

const [agreed, setAgreed] = useState(false);

<Checkbox
  label="I agree to the terms"
  checked={agreed}
  onCheckedChange={setAgreed}
/>

Inside a form:

import { DashForm } from '@dashforge/forms';
import { Checkbox, Button } from '@dashforge/tw';

<DashForm onSubmit={subscribe}>
  <Checkbox name="newsletter" label="Subscribe to the weekly digest" />
  <Checkbox name="terms" label="I accept the terms of service" required />
  <Button type="submit" color="primary">Subscribe</Button>
</DashForm>

The bridge registers the boolean automatically — no Controller wrap.

Examples

import { Checkbox, Stack } from '@dashforge/tw';

<Stack gap={2}>
  <Checkbox name="terms" label="I accept the terms and conditions" />
  <Checkbox name="newsletter" label="Send me the monthly newsletter" defaultChecked />
</Stack>

With helper text

<Checkbox
  label="Send weekly digest"
  helper="A Monday morning summary of activity in your workspace."
/>

Helper text is rendered below the label in a muted color. Keep it short — one sentence — so the row stays scannable in a settings list.

Uncontrolled vs controlled

{/* Uncontrolled — internal state */}
<Checkbox label="Auto-save" defaultChecked />

{/* Controlled — you own the state */}
<Checkbox label="Auto-save" checked={autoSave} onCheckedChange={setAutoSave} />

onCheckedChange is the Radix-style callback — receives the next boolean directly (no synthetic event). Use onChange if you need the underlying input event.

Indeterminate

const [checked, setChecked] = useState<boolean | 'indeterminate'>('indeterminate');

<Checkbox
  label="Select all"
  checked={checked}
  onCheckedChange={setChecked}
/>

Pass the literal string 'indeterminate' as the checked value (or set it via state) to render the dash glyph. Useful for "select all" patterns where some children are selected.

Disabled

import { Checkbox, Stack } from '@dashforge/tw';

<Stack gap={2}>
  <Checkbox name="state-unchecked" label="Unchecked" />
  <Checkbox name="state-checked" label="Checked" defaultChecked />
  <Checkbox name="state-disabled" label="Disabled" disabled />
  <Checkbox name="state-disabled-checked" label="Disabled + checked" disabled defaultChecked />
</Stack>

<Checkbox label="Premium feature" disabled helper="Upgrade your plan to enable." />

Disabled checkboxes are removed from tab order and rendered at reduced opacity. The label is also dimmed for visual coherence.

Error state

import { Checkbox } from '@dashforge/tw';

<Checkbox
  name="terms-required"
  label="I accept the terms and conditions"
  error
  helperText="You must accept the terms to continue."
/>

When error is set, the checkbox renders with the danger ring and the helper text turns red — same convention as TextField.

RBAC gating

<Checkbox
  name="adminFlag"
  label="Mark as VIP"
  access={{ requires: 'workspace.admin', when: 'denied:hide' }}
/>

Three when modes ('denied:hide' | 'denied:disable' | 'denied:readonly') — same semantics as Button and TextField.

Settings list pattern

The classic three-row settings panel:

<div className="space-y-2">
  <Checkbox name="emailNotifs" label="Email notifications"
    helper="Weekly activity digest." defaultChecked />
  <Checkbox name="pushNotifs"  label="Push notifications"
    helper="Real-time alerts in your browser." />
  <Checkbox name="smsNotifs"   label="SMS notifications"
    helper="Critical security alerts only." />
</div>

Theme defaults

Configure <Checkbox> defaults application-wide.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    Checkbox: {
      defaults: { size: 'md' },
    },
  },
});

Configurable axes (CheckboxVariantProps):

Non-visual axes (name, rules, label, helperText, error, disabled, checked, defaultChecked, access, visibleWhen, onCheckedChange) are not theme-configurable.

Precedence chain (lowest → highest):

1. defaultVariants from the internal checkboxVariants recipe.
2. theme.components.Checkbox.defaults (application-wide).
3. Instance prop (<Checkbox size="lg" />) — wins over theme.
4. sx — appended to the root and wins over conflicting classes via tailwind-merge.

TypeScript: theme.components.Checkbox.defaults autocompletes to size only; unrecognized fields are compile-time errors.

Reactivity: useComponentDefaults('Checkbox') subscribes to the theme store — patchTheme re-renders every mounted instance inheriting the changed axis.

API

Props

Slots & slotProps

<Checkbox> is a compound component with 6 named slots. Each slot accepts a { className?: string } override via slotProps:

Use sx for a root-level class override; use slotProps when you need to reach a specific inner element (e.g. control border color, errorText font style).

Notes

• Backed by Radix (@radix-ui/react-checkbox) — the accessibility primitives are not hand-rolled. Indeterminate state, focus management, and keyboard handling are Radix's responsibility, not ours.
• The visible "box" is NOT an <input type="checkbox"> — it's a styled <button role="checkbox">. A real hidden <input> is present for form serialization compatibility (browsers POST the value when a <form> is submitted natively).
• Click target extends to the entire row (label + box) — clicking the helper text also toggles the value. Better fat-finger ergonomics on touch devices.
• Indeterminate is purely visual — it doesn't submit any value to the form. The form sees the checkbox as unchecked. Use a separate <input type="hidden"> if you need to persist the indeterminate semantics.