Checkbox — Design System

Examples

Basic choice

A labeled checkbox supports a native binary choice in a form or settings group.

Weekly digest

Receive one summary each Monday.

Labeled Checkbox with supporting description

"use client";

import { Checkbox } from "@phuctech/ui/components/checkbox";
import { Field, FieldDescription, FieldLabel } from "@phuctech/ui/components/field";

export function Example() {
  return (
    <Field>
      <FieldLabel htmlFor="checkbox-digest">Weekly digest</FieldLabel>
      <div className="flex items-center gap-2">
        <Checkbox id="checkbox-digest" name="digest" value="enabled" />
        <FieldDescription>Receive one summary each Monday.</FieldDescription>
      </div>
    </Field>
  );
}

Density

Use sm, md, or lg so the control matches the surrounding form rhythm.

SmallDefaultLarge

Checkbox small, default, and large sizes

"use client";

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

export function Example() {
  return (
    <div className="flex flex-wrap items-center gap-6 text-sm">
      <label className="flex items-center gap-2"><Checkbox size="sm" defaultChecked aria-label="Small density" />Small</label>
      <label className="flex items-center gap-2"><Checkbox size="md" defaultChecked aria-label="Default density" />Default</label>
      <label className="flex items-center gap-2"><Checkbox size="lg" defaultChecked aria-label="Large density" />Large</label>
    </div>
  );
}

Controlled state

Feature state owns the checked value when another part of the screen depends on it.

Controlled Checkbox preview

"use client";

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

export function Example() {
  return <Checkbox aria-label="Email updates" checked={true} disabled={false} indeterminate={false} />;
}

Indeterminate selection

A parent checkbox communicates that only some visible rows are selected.

Select all visible projects

Atlas onboardingOrbit billing

Indeterminate parent Checkbox and child choices

"use client";

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

export function Example() {
  return (
    <div className="grid gap-3">
      <label className="flex items-center gap-2 text-sm font-medium">
        <Checkbox aria-label="Select all visible projects" indeterminate />
        Select all visible projects
      </label>
      <div className="grid gap-2 pl-6 text-sm text-muted-foreground">
        <label className="flex items-center gap-2"><Checkbox defaultChecked aria-label="Atlas onboarding" />Atlas onboarding</label>
        <label className="flex items-center gap-2"><Checkbox aria-label="Orbit billing" />Orbit billing</label>
      </div>
    </div>
  );
}

Disabled, read-only, and invalid

Unavailable and validation states remain paired with readable context.

Unavailable optionInherited option

Required confirmation

This choice is required.

Checkbox disabled, read-only, and invalid states

"use client";

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

export function Example() {
  return (
    <div className="grid gap-3 text-sm">
      <label className="flex items-center gap-2"><Checkbox defaultChecked aria-label="Required consent" required />Required consent</label>
      <label className="flex items-center gap-2"><Checkbox aria-label="Unavailable option" disabled />Unavailable option</label>
      <label className="flex items-center gap-2"><Checkbox defaultChecked aria-label="Inherited option" readOnly />Inherited option</label>
      <label className="flex items-center gap-2"><Checkbox aria-label="Invalid option" aria-invalid="true" />Invalid option</label>
    </div>
  );
}

Native form value

name, value, required, and uncheckedValue integrate with a native form.

Checkbox with native form attributes

"use client";

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

export function Example() {
  return (
    <form className="grid gap-3" onSubmit={(event) => event.preventDefault()}>
      <label className="flex items-center gap-2 text-sm"><Checkbox name="marketing" value="enabled" uncheckedValue="disabled" defaultChecked />Marketing notifications</label>
      <Button type="submit" size="sm">Save preferences</Button>
    </form>
  );
}

When to use

Use a checkbox when several independent options may be selected together. Use RadioGroup for one choice from a set, and Switch when a setting takes effect immediately.

Usage

"use client";

import { Checkbox } from "@phuctech/ui/components/checkbox";
import { Field, FieldDescription, FieldLabel } from "@phuctech/ui/components/field";

export function Example() {
  return (
    <Field>
      <FieldLabel htmlFor="checkbox-digest">Weekly digest</FieldLabel>
      <div className="flex items-center gap-2">
        <Checkbox id="checkbox-digest" name="digest" value="enabled" />
        <FieldDescription>Receive one summary each Monday.</FieldDescription>
      </div>
    </Field>
  );
}

Pair the control with a visible FieldLabel. Keep validation and selection business rules in the feature; Checkbox only exposes the control state.

States

Checkbox states
State	Guidance
`checked`	Controlled state for a feature-owned value.
`defaultChecked`	Initial state for a local uncontrolled form control.
`indeterminate`	Use for a parent selection when only some child values are selected.
`disabled / readOnly`	Keep the reason understandable without relying on color.

API

Component API
Prop	Type	Default	Description	Constraints
`checked / defaultChecked`	`boolean`	`false`	Controlled or initial selection state.	Choose one state model per instance.
`onCheckedChange`	`(checked, details) => void`	`—`	Called when the selection changes.	Update controlled feature state here.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Control density for the square and its indicator.	Match the surrounding form rhythm.
`indeterminate`	`boolean`	`false`	Displays a mixed selection state.	Use for a parent checkbox, not as a third submitted value.
`disabled / readOnly / required`	`boolean`	`false`	Native interaction and form semantics.	Pair non-obvious constraints with visible text.
`name / value / form / uncheckedValue`	`string`	`—`	Native form submission fields.	Use stable names in a form.
`className / ref / render`	`string / Ref / element`	`—`	Style extension and Base UI composition.	Preserve the checkbox semantics when composing.

Tokens

Component tokens
Token	Role	Effective value	Usage
`--radius-sm`	Checkbox radius	`0.375rem`	Keeps the square control softly rounded across sizes.
`--color-action-primary / --color-border-strong`	Selection	`semantic roles`	Checked and unchecked states remain distinct in both themes.
`--focus-ring-*`	Keyboard focus	`shared ring`	Keeps Space activation visible.

Accessibility

Give every Checkbox a visible label or an explicit accessible name.
Use aria-checked="mixed" through indeterminate for partial selection.
Verify Space toggles the control and that the label is part of the accessible name.

RadioGroup handles mutually exclusive choices.
Field connects labels, descriptions, and errors.
Data table composes Checkbox for visible-row selection.