Get Started
Components
- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
AI Elements
Libraries
Utilities
"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
$ bunx --bun frakment add checkbox$ npx frakment add checkbox$ pnpm dlx frakment add checkbox$ yarn dlx frakment add checkbox
Install the following dependencies:
$ bun add lucide-react$ npm install lucide-react$ pnpm add lucide-react$ yarn add lucide-react
Copy and paste the following code into your project.
"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 };Update the import paths to match your project setup.
Usage
import { Checkbox } from "@/components/ui/checkbox";
<DocsBaseSwitcher base="web" component="checkbox" className="mb-6" /><Checkbox defaultChecked />Examples
States
Pass checked="indeterminate" for a partial-selection state.
"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>
);
}<Checkbox aria-label="Unchecked" />
<Checkbox aria-label="Checked" defaultChecked />
<Checkbox aria-label="Indeterminate" checked="indeterminate" />Disabled
"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>
);
}<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.
"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>
);
}<div className="flex items-center gap-2">
<Checkbox id="c-a" defaultChecked />
<Label htmlFor="c-a">Email notifications</Label>
</div>In Context
Terms acceptance
"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
"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">.
| Prop | Type | Default | Description |
|---|---|---|---|
checked | boolean"indeterminate" | — | Controlled state. Use "indeterminate" for partial selection. |
defaultChecked | boolean"indeterminate" | false | Uncontrolled initial state. |
onCheckedChange | (checked: boolean | "indeterminate") => void | — | Fires when the checkbox toggles. |
disabled | boolean | false | Removes the checkbox from the tab order. |
required | boolean | false | Native form requirement. |
Controlled
const [checked, setChecked] = React.useState(false)
<Checkbox checked={checked} onCheckedChange={setChecked} />States
| State | How |
|---|---|
| Unchecked | default |
| Checked | checked prop |
| Indeterminate | checked="indeterminate" |
| Disabled | disabled prop |
Data Attributes
| Attribute | Values |
|---|---|
data-slot | checkbox |
data-state | checked | unchecked | indeterminate |
data-disabled | true |
Accessibility
Checkboxrenders a button withrole="checkbox"and managesaria-checked. Do not addrolemanually.- Always pair with a
labelorFieldLabelusinghtmlFor. 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. disabledremoves the checkbox from the tab order. If the value is informational, usereadOnlyinstead ofdisabled.
Best Practices
- One checkbox per independent option. Do not use it for exclusive choices — use
RadioGroup. - Labels go to the right.
Checkboxthenlabelis 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
Switchfor immediate settings. Checkbox reads as "queued until save" to many users.
Related Components
- Radio Group — single choice
- Switch — on/off toggle
- Field — label + description
Anatomy
"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-primarywhen checked - Indicator — checkmark icon, rendered only when checked
- Label — separate element, linked with
htmlFor