# Checkbox

Page: /docs/components/checkbox

{/* Figma: Meridian → Checkbox (docs 40:34, component sets 18:858 and 18:1162). Spec: docs/design-system/meridian/checkbox.md */}

A choice people turn on or off, alone or in a list. 16 square with radius 4, its label (14) and an optional description built in. On HubSpot forms it carries consent and "send me the guide" choices.

```tsx
import { Checkbox } from "@commenda/meridian/ui/checkbox";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function CheckboxChecked() {
	return (
		<Stage>
			<Labelled label="unchecked">
				<Checkbox label="Send me the monthly tax brief" />
			</Labelled>
			<Labelled label="checked">
				<Checkbox label="Send me the monthly tax brief" defaultChecked />
			</Labelled>
			<Labelled label="indeterminate">
				<Checkbox label="All products" indeterminate />
			</Labelled>
		</Stage>
	);
}
```

## Usage [#usage]

```tsx
import { Checkbox } from "@commenda/meridian/ui/checkbox";

<Checkbox label="Send me the monthly tax brief" onCheckedChange={setSubscribed} />;
```

## Checked, unchecked, indeterminate [#checked-unchecked-indeterminate]

Indeterminate shows a parent when only some of its children are checked. Clicking it checks them all.

```tsx
import { Checkbox } from "@commenda/meridian/ui/checkbox";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function CheckboxChecked() {
	return (
		<Stage>
			<Labelled label="unchecked">
				<Checkbox label="Send me the monthly tax brief" />
			</Labelled>
			<Labelled label="checked">
				<Checkbox label="Send me the monthly tax brief" defaultChecked />
			</Labelled>
			<Labelled label="indeterminate">
				<Checkbox label="All products" indeterminate />
			</Labelled>
		</Stage>
	);
}
```

## With a description [#with-a-description]

One line under the label when the choice needs explaining.

```tsx
import { Checkbox } from "@commenda/meridian/ui/checkbox";

function Panel({ children, grid = false }: { children: React.ReactNode; grid?: boolean }) {
	return (
		<div
			className={`not-prose my-4 rounded-xl border border-fd-border bg-white p-8 ${
				grid ? "grid gap-4 md:grid-cols-3" : "flex flex-col gap-2"
			}`}
		>
			{children}
		</div>
	);
}

export function CheckboxDescription() {
	return (
		<Panel>
			<Checkbox
				label="I agree to receive emails from Commenda"
				description="You can unsubscribe at any time. See our privacy policy."
				defaultChecked
			/>
		</Panel>
	);
}
```

## A group [#a-group]

A parent with its children indented 24, 8 apart. The parent is indeterminate while only some are on. Try it: the parent follows its children.

```tsx
"use client";

import { Checkbox } from "@commenda/meridian/ui/checkbox";
import { useState } from "react";

function Panel({ children, grid = false }: { children: React.ReactNode; grid?: boolean }) {
	return (
		<div
			className={`not-prose my-4 rounded-xl border border-fd-border bg-white p-8 ${
				grid ? "grid gap-4 md:grid-cols-3" : "flex flex-col gap-2"
			}`}
		>
			{children}
		</div>
	);
}

const PRODUCTS = ["Sales tax", "Transfer pricing", "Entity management"];

/** Parent with indented children; the parent is indeterminate while only some are on. */
export function CheckboxGroup() {
	const [on, setOn] = useState<string[]>(["Sales tax", "Transfer pricing"]);
	const all = on.length === PRODUCTS.length;
	return (
		<Panel>
			<Checkbox
				label="All products"
				checked={all}
				indeterminate={on.length > 0 && !all}
				onCheckedChange={(checked) => setOn(checked ? PRODUCTS : [])}
			/>
			<div className="flex flex-col gap-2 ps-6">
				{PRODUCTS.map((product) => (
					<Checkbox
						key={product}
						label={product}
						checked={on.includes(product)}
						onCheckedChange={(checked) =>
							setOn((prev) => (checked ? [...prev, product] : prev.filter((p) => p !== product)))
						}
					/>
				))}
			</div>
		</Panel>
	);
}
```

## States [#states]

Hover darkens the border. Focus is the 2px blue ring with a white gap, from the keyboard only. Disabled keeps its label readable.

```tsx
import { Checkbox } from "@commenda/meridian/ui/checkbox";
import type { ReactNode } from "react";

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function CheckboxStates() {
	return (
		<div className="not-prose my-4 flex flex-col gap-6 rounded-xl border border-fd-border bg-white p-8">
			{[false, true].map((checked) => (
				<div key={String(checked)} className="flex flex-wrap items-end gap-8">
					<Labelled label={checked ? "checked · default" : "unchecked · default"}>
						<Checkbox label="Send me a copy" defaultChecked={checked} />
					</Labelled>
					<Labelled label="disabled">
						<Checkbox
							label="Send me a copy"
							defaultChecked={checked}
							disabled
							disabledReason="Copies are off for this form"
						/>
					</Labelled>
				</div>
			))}
			<p className="text-[12px] text-fd-muted-foreground">Hover and Tab to see hover and focus.</p>
		</div>
	);
}
```

## Checkbox card [#checkbox-card]

Radio card’s sibling, for choices where several can be picked and each needs a title and a description, like the products someone wants a demo of. The whole card is the click target and carries the focus ring.

```tsx
import { Checkbox } from "@commenda/meridian/ui/checkbox";

function Panel({ children, grid = false }: { children: React.ReactNode; grid?: boolean }) {
	return (
		<div
			className={`not-prose my-4 rounded-xl border border-fd-border bg-white p-8 ${
				grid ? "grid gap-4 md:grid-cols-3" : "flex flex-col gap-2"
			}`}
		>
			{children}
		</div>
	);
}

export function CheckboxCards() {
	const cards = [
		["Sales tax", "Registration, filing and nexus tracking.", true],
		["Transfer pricing", "Policies, benchmarking and local files.", true],
		["Entity management", "Annual reports and registered agents.", false],
		["Tax and accounting", "Bookkeeping and corporate returns.", false],
		["Global indirect tax", "VAT and GST in 100+ countries.", true],
	] as const;
	return (
		<Panel grid>
			{cards.map(([label, description, checked]) => (
				<Checkbox
					key={label}
					variant="card"
					label={label}
					description={description}
					defaultChecked={checked}
				/>
			))}
			<Checkbox
				variant="card"
				label="Payroll"
				description="Coming soon."
				disabled
				disabledReason="Payroll is not available yet"
			/>
		</Panel>
	);
}
```

## Anatomy [#anatomy]

Box 16, radius 4, 1px border soft-pearl 400. Checked and indeterminate fill blue 700 with a white 12 mark. The label is 14 and sits 8 to the right; the description is 14 in soft-pearl 800, 2 below.

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `hideLabel` | `boolean` |  |
| `description` | `string` |  |
| `disabledReason` | `string` |  |
| `variant` | `"default" \| "card"` |  |
| `details` | `readonly string[]` |  |
| `leading` | `ReactNode` |  |
| `className` | `string` |  |
| `onCheckedChange` | `(checked: boolean) => void` |  |
| `defaultChecked` | `boolean` | Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead. |
| `style` | `CSSProperties \| ((state: CheckboxRootState) => CSSProperties \| undefined)` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `form` | `string` | Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form. |
| `disabled` | `boolean` | Whether the component should ignore user interaction. |
| `name` | `string` | Identifies the field when a form is submitted. |
| `value` | `string` | The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on". |
| `id` | `string` | The id of the input element. |
| `readOnly` | `boolean` | Whether the user should be unable to tick or untick the checkbox. |
| `required` | `boolean` | Whether the user must tick the checkbox before submitting a form. |
| `inputRef` | `((instance: HTMLInputElement \| null) => void \| (() => VoidOrUndefinedOnly) \| DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) \| RefObject<HTMLInputElement \| null>` | A ref to access the hidden `<input>` element. |
| `checked` | `boolean` | Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead. |
| `indeterminate` | `boolean` | Whether the checkbox is in a mixed state: neither ticked, nor unticked. |
| `uncheckedValue` | `string` | The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior. |

## Best practices [#best-practices]

- Use a Checkbox for choices that send with the form. For a setting that applies the moment it changes, use a Switch.
- One Checkbox alone asks a yes or no question. In a list, every box is independent; for one choice from a few, use Radio.
- Labels say what is turned on ("Send me the monthly tax brief"), never a question ("Do you want the brief?").
- Marketing consent is never pre-checked. Its label matches the HubSpot subscription type it sets.
- The label is part of the click target, not just the box.
- Indeterminate is only for a parent of checkboxes, never a third answer.
- Source: Pathfinder Checkbox. Meridian sets labels in 14 and descriptions in 14.
