JM Family Design System

Checkbox

Checkboxes capture independent yes/no choices or multiple selections from a set. Use them when each option can be selected without canceling another.

Guidance for adoption

Start here before choosing examples or props. These notes explain where Checkbox helps, where another pattern is better, and what should stay true in product work.

When to use

  • Independent options
  • Multi-select lists
  • Acknowledgements and consent

When not to use

  • Mutually exclusive choices
  • Immediate on/off system settings

Accessibility expectations

  • Associate labels with controls.
  • Group related checkboxes with fieldset and legend.
  • Expose indeterminate state when used for parent selection.

Content guidance

  • Write labels as affirmative statements that describe the selected state, such as "Send status updates".
  • For acknowledgement or consent, put the user commitment in the label instead of hiding it in helper text.
  • Use helper text for context that helps people decide whether to check the option.
  • Use group legends to name the question when related checkboxes belong together.

Implementation notes

  • Wrap related checkboxes in a fieldset with a legend; the component does not provide a group primitive.
  • Use indeterminate only when a parent checkbox summarizes a mixed group of child selections.
  • Helper text is wired to aria-describedby; group-level errors and aria-invalid need to be handled by the parent.
  • Use Checkbox for deferred form values. Use Toggle when a setting changes immediately.

Import

import { Checkbox } from '@/components/ui/Checkbox';

Native checkbox with label, helper text, and indeterminate state baked in.

States

Checkbox states should be easy to scan and programmatically clear. Use indeterminate only when a parent control summarizes a mixed group of child selections.

Unchecked

The option is available but not selected.

Checked

The option is selected and can be changed independently.

Indeterminate

A parent option represents a mixed selection in a child group.

Disabled

The option cannot be changed in the current workflow state.

Anatomy

A checkbox is small, but the label and group context carry most of the meaning. Keep the interactive target and the text close together.

Vendor options
  1. Checkbox control
  2. Visible label
  3. Checked state
  4. Optional helper text
  5. Group legend
  6. Focus and disabled state

Props

The component accepts every native HTMLInputElement attribute on top of the design system props below.

PropTypeDefaultDescription
labelReactNode—Visible label rendered beside the checkbox. Required for accessibility.
helperReactNode—Secondary text below the label. Auto-wired to aria-describedby.
indeterminatebooleanfalseShows a dash icon. Use only when a parent checkbox summarizes a mixed child group.

Usage rules

Use for independent choices

Each checkbox should stand on its own. Turning one option on should not automatically turn another option off.

Do not use for mutually exclusive options

When only one option can be chosen from a group, use radio buttons or select instead.

Write labels as clear statements

Use labels that describe the selected state, such as "Include inactive vendors" or "Send email updates".

Do not hide required terms in helper text

For acknowledgement or consent, the checkbox label should contain the user commitment clearly.

Known limitations

What Checkbox does not do yet, and what consumers need to compose themselves.

  • No error or invalid state. The component accepts helper text but exposes no error prop, no aria-invalid wiring, and no error styling; form validation messaging must be handled by the parent.
  • No checkbox-group primitive. Grouped checkboxes need an external fieldset, legend, and shared description; the component does not provide a group wrapper or required indicator.

Agent guidance

Agents should use checkboxes for independent options and multi-select groups, not as a visual substitute for radio buttons, toggles, or submit actions.

Generation rules

  • Use checkbox groups for multiple selections.
  • Write labels as clear affirmative statements.
  • Do not use a checkbox when only one option can be selected.
  • Wrap a group of checkboxes in a fieldset with a legend describing the question. The component does not ship a group primitive, so the legend and shared aria-describedby must be added by the consumer.
  • For form-level errors, render an Alert above the fieldset and link related checkboxes to it with aria-describedby. The component exposes no error prop or aria-invalid wiring.
  • Use indeterminate only on a parent that summarizes mixed child state. Setting indeterminate on a leaf checkbox to mean "maybe" is a misuse of the state.
  • For immediate on/off settings such as notifications or dark mode, swap in a Toggle. Checkboxes imply a deferred submit, which misleads users on live preferences.

Baseline example

import { Checkbox } from '@/components/ui/Checkbox';

<fieldset>
  <legend>Notifications</legend>
  <Checkbox
    label="Send status updates"
    name="notifications"
    value="status-updates"
    helper="Notify me when this request changes."
  />
</fieldset>
If checking the control immediately changes a system setting, agents should consider Toggle instead. If the user must choose one option from a set, use Radio or Select.

Decision standard

Checkbox means independent selection. If selecting one option changes the meaning or availability of another option, document that relationship in the surrounding pattern.