For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Checkbox

A control that allows the user to toggle between checked and not checked.

checkbox.tsx
"use client";

import { CheckIcon } from "lucide-react";
import * as React from "react";

import { cn } from "@/lib/utils";

type CheckedState = boolean | "indeterminate";

type CheckboxProps = Omit<
  React.ComponentPropsWithoutRef<"button">,
  "onChange" | "role" | "aria-checked" | "type"
> & {
  checked?: CheckedState;
  defaultChecked?: CheckedState;
  disabled?: boolean;
  onCheckedChange?: (checked: CheckedState) => void;
  ref?: React.Ref<HTMLButtonElement>;
};

function Checkbox({
  checked: checkedProp,
  className,
  defaultChecked = false,
  disabled = false,
  onClick,
  onCheckedChange,
  ref,
  ...props
}: CheckboxProps) {
  const isControlled = checkedProp !== undefined;
  const [uncontrolled, setUncontrolled] =
    React.useState<CheckedState>(defaultChecked);
  const checked = isControlled ? checkedProp : uncontrolled;
  const isChecked = checked === true;
  const isIndeterminate = checked === "indeterminate";
  const isActive = isChecked || isIndeterminate;
  const dataState = isIndeterminate
    ? "indeterminate"
    : isChecked
      ? "checked"
      : "unchecked";
  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
    onClick?.(event);
    if (event.defaultPrevented || disabled) {
      return;
    }
    const next: CheckedState = !isChecked;
    if (!isControlled) {
      setUncontrolled(next);
    }
    onCheckedChange?.(next);
  };
  return (
    <button
      aria-checked={isIndeterminate ? "mixed" : isChecked}
      className={cn(
        "peer border-input group-has-[:focus-visible]/field-label:not-data-checked:border-input focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground group-has-[:focus-visible]/field-label:data-checked:border-primary dark:data-checked:bg-primary relative flex size-4 shrink-0 items-center justify-center rounded-[4px] border transition-colors outline-none group-has-disabled/field:opacity-50 group-has-[:focus-visible]/field-label:ring-0 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:ring-3 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:ring-3",
        className
      )}
      data-checked={isActive ? "" : undefined}
      data-slot="checkbox"
      data-state={dataState}
      disabled={disabled}
      onClick={handleClick}
      ref={ref}
      role="checkbox"
      type="button"
      {...props}
    >
      {isActive ? (
        <span
          aria-hidden="true"
          className="grid place-content-center text-current [&>svg]:size-3.5"
          data-slot="checkbox-indicator"
        >
          {isIndeterminate ? (
            <span className="block h-px w-2 rounded-full bg-current" />
          ) : (
            <CheckIcon />
          )}
        </span>
      ) : null}
    </button>
  );
}

export { Checkbox };

Checkbox is a native button styled with Frakment tokens. It supports checked, unchecked, and indeterminate states, and integrates with Label for accessible click-through.

Installation

Usage

checkbox.tsx
import { Checkbox } from "@/components/ui/checkbox";
<DocsBaseSwitcher base="web" component="checkbox" className="mb-6" />
tsx
<Checkbox defaultChecked />

Examples

States

Pass checked="indeterminate" for a partial-selection state.

checkbox-states.tsx
"use client";

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

export function CheckboxStates() {
  return (
    <div className="flex items-center gap-4">
      <Checkbox aria-label="Unchecked" />
      <Checkbox aria-label="Checked" defaultChecked />
      <Checkbox aria-label="Indeterminate" checked="indeterminate" />
    </div>
  );
}
tsx
<Checkbox aria-label="Unchecked" />
<Checkbox aria-label="Checked" defaultChecked />
<Checkbox aria-label="Indeterminate" checked="indeterminate" />

Disabled

checkbox-disabled.tsx
"use client";

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

export function CheckboxDisabled() {
  return (
    <div className="flex items-center gap-2 [&>*]:shrink-0">
      <Checkbox disabled id="c-dis" />
      <Label htmlFor="c-dis">Disabled</Label>
    </div>
  );
}
tsx
<Checkbox id="c-dis" disabled />
<Label htmlFor="c-dis">Disabled</Label>

With label

Pair with Label and matching id / htmlFor for a click-through row.

checkbox-with-label.tsx
"use client";

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

export function CheckboxWithLabel() {
  return (
    <div className="flex flex-col gap-3 [&_label]:h-4">
      <div className="flex items-center gap-2 [&>*]:shrink-0">
        <Checkbox defaultChecked id="c-a" />
        <Label htmlFor="c-a">Email notifications</Label>
      </div>
      <div className="flex items-center gap-2 [&>*]:shrink-0">
        <Checkbox id="c-b" />
        <Label htmlFor="c-b">SMS notifications</Label>
      </div>
    </div>
  );
}
tsx
<div className="flex items-center gap-2">
  <Checkbox id="c-a" defaultChecked />
  <Label htmlFor="c-a">Email notifications</Label>
</div>

In Context

Terms acceptance

checkbox-terms.tsx
"use client";

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

export function CheckboxTerms() {
  return (
    <div className="mx-auto flex max-w-sm items-center gap-2">
      <Checkbox id="terms" />
      <label className="text-sm leading-4" htmlFor="terms">
        I agree to the Terms of Service and Privacy Policy.
      </label>
    </div>
  );
}

Notification preferences

checkbox-notifications.tsx
"use client";

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

export function CheckboxNotifications() {
  return (
    <div className="mx-auto max-w-sm space-y-3">
      <div className="flex items-center gap-2">
        <Checkbox defaultChecked id="email" />
        <label className="text-sm leading-4" htmlFor="email">
          Email notifications
        </label>
      </div>
      <div className="flex items-center gap-2">
        <Checkbox id="push" />
        <label className="text-sm leading-4" htmlFor="push">
          Push notifications
        </label>
      </div>
    </div>
  );
}

API Reference

Checkbox

Extends React.ComponentProps<"button">.

PropTypeDefaultDescription
checked
boolean"indeterminate"
—Controlled state. Use "indeterminate" for partial selection.
defaultChecked
boolean"indeterminate"
falseUncontrolled initial state.
onCheckedChange(checked: boolean | "indeterminate") => void—Fires when the checkbox toggles.
disabledbooleanfalseRemoves the checkbox from the tab order.
requiredbooleanfalseNative form requirement.

Controlled

tsx
const [checked, setChecked] = React.useState(false)
<Checkbox checked={checked} onCheckedChange={setChecked} />

States

StateHow
Uncheckeddefault
Checkedchecked prop
Indeterminatechecked="indeterminate"
Disableddisabled prop

Data Attributes

AttributeValues
data-slotcheckbox
data-statechecked | unchecked | indeterminate
data-disabledtrue

Accessibility

  • Checkbox renders a button with role="checkbox" and manages aria-checked. Do not add role manually.
  • Always pair with a label or FieldLabel using htmlFor. Clicking the label toggles the checkbox.
  • The indeterminate state is set via checked="indeterminate". It has no user-triggered equivalent; set it when some but not all children are selected.
  • disabled removes the checkbox from the tab order. If the value is informational, use readOnly instead of disabled.

Best Practices

  • One checkbox per independent option. Do not use it for exclusive choices — use RadioGroup.
  • Labels go to the right. Checkbox then label is the standard pattern.
  • Instant toggle. Checkboxes toggle immediately; there is no separate save step.
  • Indeterminate is a display state. Set it programmatically when a parent has mixed child states.
  • Use Switch for immediate settings. Checkbox reads as "queued until save" to many users.

Anatomy

checkbox-anatomy.tsx
"use client";

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

export function CheckboxAnatomy() {
  return (
    <div className="flex items-center gap-2">
      <Checkbox defaultChecked id="a" />
      <label className="text-sm leading-4" htmlFor="a">
        Checked
      </label>
      <Checkbox id="b" />
      <label className="text-sm leading-4" htmlFor="b">
        Unchecked
      </label>
    </div>
  );
}
  • Box — 16px square with a 1px border, bg-primary when checked
  • Indicator — checkmark icon, rendered only when checked
  • Label — separate element, linked with htmlFor