Checkbox
A choice people turn on or off.
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.
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
import { Checkbox } from "@commenda/meridian/ui/checkbox";
<Checkbox label="Send me the monthly tax brief" onCheckedChange={setSubscribed} />;Checked, unchecked, indeterminate
Indeterminate shows a parent when only some of its children are checked. Clicking it checks them all.
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
One line under the label when the choice needs explaining.
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 parent with its children indented 24, 8 apart. The parent is indeterminate while only some are on. Try it: the parent follows its children.
"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
Hover darkens the border. Focus is the 2px blue ring with a white gap, from the keyboard only. Disabled keeps its label readable.
Hover and Tab to see hover and focus.
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
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.
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
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
| Prop | Type | Description |
|---|---|---|
labelRequired | string | From Pathfinder. |
hideLabel | boolean | From Pathfinder. |
description | string | From Pathfinder. |
disabledReason | string | From Pathfinder. |
variant | "default" | "card" | From Pathfinder. |
details | readonly string[] | From Pathfinder. |
leading | ReactNode | From Pathfinder. |
className | string | From Pathfinder. |
onCheckedChange | (checked: boolean) => void | From Pathfinder. |
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
- 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.