Skip to main content

Checkbox

BasicSelection<co-checkbox>

Checkbox turns one option on or off, alone or in a list; it also has an indeterminate state for select-all.

import { Checkbox } from 'health-components';

Examples​

Showcase​

Storybook

Indeterminate​

Storybook

With Description​

Storybook

Disabled​

Storybook

Invalid​

Storybook

Usage​

<Checkbox label="Send reminder by SMS" checked={sms} onChange={e => setSms(e.target.checked)} />

When to use​

  • Independent yes/no options: "Send reminder by SMS", "Patient declined".
  • Selecting table rows.

When not to use​

  • A setting that takes effect at once: Switch.
  • One choice from several: RadioGroup.

Variants and states​

VariantWhat it is
unchecked / checkedNative box, primary accent.
indeterminateSome rows selected.
descriptionMuted line under the label.
disabled55% opacity.

Accessibility​

  • Native input inside its label, so the whole row is clickable.

Do and don't​

  • Do: "I have reviewed the allergy list" before signing.
  • Don't: A checkbox that submits a form.

Props​

PropTypeDefaultDescription
label *ReactNode—Visible label; the whole row is clickable. Required
checkedboolean—Checked state (controlled); pair with `onChange`
defaultCheckedbooleanfalseInitial checked state (uncontrolled)
indeterminatebooleanfalseMixed state, for "select all" when only some items are selected
descriptionReactNodenoneHelp text under the label
errorbooleanfalseMarks the input invalid (aria-invalid)
disabledbooleanfalseDisables the checkbox

Also accepts native attributes, including defaultValue, autoFocus, onChange, onInput, readOnly, name, value, max, step, placeholder, accept, autoComplete, maxLength, min, multiple, required, plus className and event handlers on the root element.

Angular, Vue and HTML​

Register the elements once (Angular guide), then use <co-checkbox>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.

Angular template
<co-checkbox checked default-checked [defaultValue]="defaultValue" (co-change)="onChange($event.detail)"></co-checkbox>
KindNameDescription
attributecheckedChecked state (controlled); pair with `onChange`
attributedefault-checked / defaultCheckedInitial checked state (uncontrolled); default false
attributeindeterminateMixed state, for "select all" when only some items are selected; default false
attributeerrorMarks the input invalid (aria-invalid); default false
attributedisabledDisables the checkbox; default false
property / JSON attributedefault-value / defaultValue
attributeauto-focus / autoFocus
attributeread-only / readOnly
attributename
property / JSON attributevalue
property / JSON attributemax
property / JSON attributestep
attributeplaceholder
attributeaccept
property / JSON attributeauto-complete / autoComplete
attributemax-length / maxLength
property / JSON attributemin
attributemultiple
attributerequired
eventco-change (React: onChange)
eventco-input (React: onInput)
slotlabelVisible label; the whole row is clickable. Required Plain text also works as the `label` attribute.
slotdescriptionHelp text under the label; default none Plain text also works as the `description` attribute.