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
Indeterminate
With Description
Disabled
Invalid
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
| Variant | What it is |
|---|---|
| unchecked / checked | Native box, primary accent. |
| indeterminate | Some rows selected. |
| description | Muted line under the label. |
| disabled | 55% 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
| Prop | Type | Default | Description |
|---|---|---|---|
label * | ReactNode | — | Visible label; the whole row is clickable. Required |
checked | boolean | — | Checked state (controlled); pair with `onChange` |
defaultChecked | boolean | false | Initial checked state (uncontrolled) |
indeterminate | boolean | false | Mixed state, for "select all" when only some items are selected |
description | ReactNode | none | Help text under the label |
error | boolean | false | Marks the input invalid (aria-invalid) |
disabled | boolean | false | Disables 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>
| Kind | Name | Description |
|---|---|---|
| attribute | checked | Checked state (controlled); pair with `onChange` |
| attribute | default-checked / defaultChecked | Initial checked state (uncontrolled); default false |
| attribute | indeterminate | Mixed state, for "select all" when only some items are selected; default false |
| attribute | error | Marks the input invalid (aria-invalid); default false |
| attribute | disabled | Disables the checkbox; default false |
| property / JSON attribute | default-value / defaultValue | |
| attribute | auto-focus / autoFocus | |
| attribute | read-only / readOnly | |
| attribute | name | |
| property / JSON attribute | value | |
| property / JSON attribute | max | |
| property / JSON attribute | step | |
| attribute | placeholder | |
| attribute | accept | |
| property / JSON attribute | auto-complete / autoComplete | |
| attribute | max-length / maxLength | |
| property / JSON attribute | min | |
| attribute | multiple | |
| attribute | required | |
| event | co-change | (React: onChange) |
| event | co-input | (React: onInput) |
| slot | label | Visible label; the whole row is clickable. Required Plain text also works as the `label` attribute. |
| slot | description | Help text under the label; default none Plain text also works as the `description` attribute. |