Skip to content

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.

Checkbox (standalone)
Checkbox.Group
├── Checkbox.Legend or legend prop
└── Checkbox.Item (one per option)

Receive a weekly summary

Selected by default; you can turn it off

Unavailable for this account

Selected but currently unavailable

The application decides when to show error. An error marks the checkbox invalid and adds the message to its accessible description.

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.

Notification channels

Choose where to receive updates

Use Checkbox.Legend instead of the legend prop when the legend needs custom content or styling.

Delivery options

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.

Required notifications

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.

Notification channels

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.

  • Provide label, aria-label, or aria-labelledby for each checkbox. description and error are associated with a single checkbox through Base UI Field.
  • Space toggles a focused checkbox. Disabled checkboxes cannot be changed or submitted.
  • Give every group a visible legend or a composed Checkbox.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.
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.

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.

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 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.