Checkbox
⋯
Checkbox renders a 20px selection box with an optional label and supporting text. The check and minus indicators are internal to the control. Checkbox renders in Light and Dark. See Light and Dark.
import { Checkbox } from "@nesra/ui/checkbox";
export function Updates() { return <Checkbox label="Email updates" name="updates" value="email" />;}Checkbox is also exported from @nesra/ui.
Composition
Section titled “Composition”Checkbox (standalone)Checkbox.Group├── Checkbox.Legend or legend prop└── Checkbox.Item (one per option)Examples
Section titled “Examples”Default, checked, and disabled
Section titled “Default, checked, and disabled”import { Checkbox } from "@nesra/ui/checkbox";
export function CheckboxSingleExample() { return ( <div className="grid gap-nesra-spacing-lg"> <Checkbox label="Email updates" description="Receive a weekly summary" name="updates" value="email" /> <Checkbox label="Weekly digest" description="Selected by default; you can turn it off" defaultChecked /> <Checkbox label="SMS alerts" description="Unavailable for this account" disabled /> <Checkbox label="Push alerts" description="Selected but currently unavailable" defaultChecked disabled /> </div> );}Single validation
Section titled “Single validation”The application decides when to show error. An error marks the checkbox invalid and adds the
message to its accessible description.
import { useState } from "react";import { Checkbox } from "@nesra/ui/checkbox";
export function CheckboxSingleValidationExample() { const [checked, setChecked] = useState(false); const [submitted, setSubmitted] = useState(false); const error = submitted && !checked ? "Accept the terms to continue" : undefined;
return ( <form className="grid gap-nesra-spacing-lg" onSubmit={(event) => { event.preventDefault(); setSubmitted(true); }} > <Checkbox label="I accept the terms" checked={checked} error={error} onCheckedChange={setChecked} /> <button className="w-fit rounded-nesra-xs border border-nesra-stroke-border px-nesra-padding-lg py-nesra-padding-sm" type="submit" > Continue </button> </form> );}Checkbox.Group owns the selected string values. Its fieldset and legend name the group.
Each Checkbox.Item needs a distinct value. Give items the same name when their checked values
should be submitted under one form key.
import { useState } from "react";import { Checkbox } from "@nesra/ui/checkbox";
export function CheckboxGroupExample() { const [channels, setChannels] = useState<string[]>(["email"]);
return ( <Checkbox.Group legend="Notification channels" description="Choose where to receive updates" value={channels} onValueChange={setChannels} > <Checkbox.Item label="Email" name="channels" value="email" /> <Checkbox.Item label="SMS" name="channels" value="sms" /> <Checkbox.Item label="Push" name="channels" value="push" /> </Checkbox.Group> );}Custom legend
Section titled “Custom legend”Use Checkbox.Legend instead of the legend prop when the legend needs custom content or styling.
import { useState } from "react";import { Checkbox } from "@nesra/ui/checkbox";
export function CheckboxCustomLegendExample() { const [channels, setChannels] = useState<string[]>(["email"]);
return ( <Checkbox.Group value={channels} onValueChange={setChannels}> <Checkbox.Legend className="text-nesra-text-heading">Delivery options</Checkbox.Legend> <Checkbox.Item label="Email" value="email" /> <Checkbox.Item label="SMS" value="sms" /> </Checkbox.Group> );}Group validation
Section titled “Group validation”The application decides whether the selected values are valid and passes an error to the group.
The error marks the fieldset and its checkboxes invalid and is included in each checkbox’s
accessible description. A newly rendered error has role="alert".
An invalid unchecked box uses a stroke-destructive border. Every invalid box shows the
shadow-nesra-destructive ring (Figma Box Shadow/Destructive), and keyboard focus replaces that
ring with the focus ring. Error text uses text-destructive.
import { useState } from "react";import { Checkbox } from "@nesra/ui/checkbox";
export function CheckboxValidationExample() { const [channels, setChannels] = useState<string[]>([]); const [submitted, setSubmitted] = useState(false); const error = submitted && channels.length === 0 ? "Choose at least one channel" : undefined;
return ( <form className="grid gap-nesra-spacing-lg" onSubmit={(event) => { event.preventDefault(); setSubmitted(true); }} > <Checkbox.Group legend="Required notifications" error={error} value={channels} onValueChange={setChannels} > <Checkbox.Item label="Email" name="channels" value="email" /> <Checkbox.Item label="SMS" name="channels" value="sms" /> </Checkbox.Group> <button className="w-fit rounded-nesra-xs border border-nesra-stroke-border px-nesra-padding-lg py-nesra-padding-sm" type="submit" > Continue </button> </form> );}Indeterminate
Section titled “Indeterminate”indeterminate renders the minus indicator and sets aria-checked="mixed". It is separate from
the boolean checked value. In a select-all pattern, derive both states from the selected item
values: some selected means mixed, all selected means checked, and none selected means unchecked.
The parent checkbox’s change handler selects or clears every item.
import { useState } from "react";import { Checkbox } from "@nesra/ui/checkbox";
const channelValues = ["email", "sms", "push"];
export function CheckboxIndeterminateExample() { const [selected, setSelected] = useState<string[]>(["email"]); const allSelected = selected.length === channelValues.length; const someSelected = selected.length > 0 && !allSelected;
return ( <div className="grid gap-nesra-spacing-lg"> <Checkbox label="Select all channels" checked={allSelected} indeterminate={someSelected} onCheckedChange={(checked) => setSelected(checked ? [...channelValues] : [])} /> <Checkbox.Group legend="Notification channels" value={selected} onValueChange={setSelected}> <Checkbox.Item label="Email" value="email" /> <Checkbox.Item label="SMS" value="sms" /> <Checkbox.Item label="Push" value="push" /> </Checkbox.Group> </div> );}Light and Dark
Section titled “Light and Dark”Checkbox uses semantic roles, so it follows the nearest .dark or data-theme="dark" ancestor
with no extra props. The roles match the Figma .Box and Checkbox component bindings.
| State | Box fill | Box border | Mark | Label and description |
|---|---|---|---|---|
| Unchecked | foundation-bg-neutral |
stroke-brand-primary |
— | text-body |
| Checked / indeterminate | action-primary-default |
action-primary-default |
icon-on-brand |
text-body |
| Disabled | foundation-bg-disabled |
stroke-brand-primary |
icon-disabled |
text-support |
| Invalid | unchanged | stroke-destructive |
unchanged | error text in text-destructive |
Keyboard focus adds shadow-nesra-focus-ring (Figma Box Shadow/Focus ring). In Dark,
action-primary-default is near white, so the checked box is light and icon-on-brand makes the mark
near black. Group description text uses text-support.
Accessibility
Section titled “Accessibility”- Provide
label,aria-label, oraria-labelledbyfor each checkbox.descriptionanderrorare associated with a single checkbox through Base UI Field. Spacetoggles a focused checkbox. Disabled checkboxes cannot be changed or submitted.- Give every group a visible
legendor a composedCheckbox.Legend. Group description and error are associated with its items. The application owns the validation rule and when to show errors. - Keep focus styling visible when overriding
className.
API reference
Section titled “API reference”Checkbox
Section titled “Checkbox”| Prop | Type | Default | Effect |
|---|---|---|---|
label |
ReactNode |
— | Renders a visible associated label. |
description |
ReactNode |
— | Adds supporting text and an accessible description. |
error |
ReactNode |
— | Shows a message and marks the checkbox invalid. |
invalid |
boolean |
false |
Marks the checkbox invalid without requiring a message. |
checked |
boolean |
— | Controls checked state. |
defaultChecked |
boolean |
false |
Initializes uncontrolled checked state. |
indeterminate |
boolean |
false |
Shows the minus indicator and mixed state. |
onCheckedChange |
(checked: boolean, details) => void |
— | Receives user changes. |
Checkbox forwards Base UI Checkbox Root props, including id, name, value, required,
disabled, inputRef, form, and readOnly. Its ref points to the visible checkbox root.
inputRef points to the hidden form input. A checked checkbox with name and value contributes
that value to form submission.
Checkbox.Group
Section titled “Checkbox.Group”| Prop | Type | Default | Effect |
|---|---|---|---|
value |
string[] |
— | Controls selected item values. |
defaultValue |
string[] |
— | Initializes uncontrolled selected values. |
onValueChange |
(values: string[], details) => void |
— | Receives group changes. |
legend |
ReactNode |
— | Names the native fieldset. |
description |
ReactNode |
— | Adds shared supporting text. |
error |
ReactNode |
— | Shows a shared error and marks items invalid. |
invalid |
boolean |
false |
Marks the group and items invalid. |
Checkbox.Group forwards Base UI Checkbox Group props, including allValues and disabled. Its
ref points to the Base UI group container. className styles the nested fieldset. The select-all
example derives its parent state from the controlled group value.
Checkbox.Item
Section titled “Checkbox.Item”| Prop | Type | Default | Effect |
|---|---|---|---|
value |
string |
required | Identifies the item in the group. |
Checkbox.Item inherits Checkbox props and its visible-root ref. Set name on each item to
submit checked values under a form key.
Checkbox.Legend
Section titled “Checkbox.Legend”Checkbox.Legend renders a native <legend> inside Checkbox.Group. It accepts native legend
props, including className, and forwards its ref to that element. Use it instead of the group’s
legend prop when styling or composing the legend.
Styles use the semantic color roles, layout scale, and shape tokens.