Checkbox

Checkbox is a native checkbox with a styled control, label, supporting description, validation message, disabled state, and indeterminate state.

It supports three visual sizes—default, sm, and xs—plus a loading state and optional custom icons for checked or indeterminate states.

Basic usageCopy Anchor Link

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

<Checkbox label="Send me product updates" />

The component forwards native checkbox attributes such as name, value, required, checked, defaultChecked, disabled, and onChange.

Controlled and uncontrolled valuesCopy Anchor Link

Use defaultChecked for an uncontrolled checkbox:

<Checkbox label="Accept terms" defaultChecked />

Use checked and onChange when the parent owns the value:

const [accepted, setAccepted] = useState(false);

<Checkbox
  label="Accept terms"
  checked={accepted}
  onChange={(event) => setAccepted(event.target.checked)}
/>

Description and validationCopy Anchor Link

<Checkbox
  label="Share analytics"
  description="Helps us improve the product."
/>

<Checkbox
  label="Accept terms"
  error="You must accept the terms to continue."
  required
/>

Descriptions and errors are connected through aria-describedby; an error also sets aria-invalid unless explicitly overridden.

Indeterminate stateCopy Anchor Link

Use indeterminate for a parent selection whose children are only partly selected. This is a visual and native checkbox state; the parent should still manage the selected-child logic.

<Checkbox label="Select all projects" indeterminate />

SizesCopy Anchor Link

<Checkbox label="Default" size="default" />
<Checkbox label="Small" size="sm" />
<Checkbox label="Extra small" size="xs" />

Custom state iconsCopy Anchor Link

Pass checkedIcon or indeterminateIcon when the default checkmark or dash should be replaced by an icon or another React node.

import { Check, Minus } from '@mosmox-ui/icons';

<Checkbox label="Verified" checked defaultChecked checkedIcon={<Check />} />
<Checkbox label="Partially selected" indeterminate indeterminateIcon={<Minus />} />

Loading stateCopy Anchor Link

Set loading while saving a checkbox change. The control becomes disabled and shows a spinner until the parent turns loading off.

<Checkbox label="Saving preference…" checked loading />

Disabled stateCopy Anchor Link

<Checkbox label="Unavailable option" disabled />
<Checkbox label="Disabled and selected" disabled defaultChecked />

Disabled checkboxes cannot receive normal user interaction and use the shared disabled opacity token treatment.

AccessibilityCopy Anchor Link

• the visible label is associated with the native checkbox through the wrapping label;
• keyboard focus uses a visible focus ring;
• required, disabled, checked, and indeterminate preserve native checkbox semantics;
• descriptions and errors are announced through aria-describedby;
• use a label that describes the choice instead of relying on visual context alone.

Styling modelCopy Anchor Link

Checkbox colors, typography, focus, surface, and disabled treatment use shared theme tokens. Checkbox-only geometry and checkmark drawing are in Checkbox.css.

API ReferenceCopy Anchor Link

Other supported native checkbox input attributes are forwarded to the underlying <input>.