Components / Controls

Checkbox

A checkbox with a label, for choices that are independent of each other. It is a native input under a drawn box, so forms, reset and keyboard work as the browser does them. For a setting that takes effect immediately, use Switch.

Source Edit this page

Checked shows mark

When to use

Several options where any number can be on.
A single agreement or preference saved with a form.
A "select all" row with indeterminate when only some items are chosen.
A list of tasks, with strikeWhenChecked so a finished task reads as done.

Use something else when:

the change applies immediately: Switch
exactly one option may be chosen: RadioGroup
it triggers an action: Button

Usage

tsx

import { Checkbox } from "@arshad-shah/cynosure";

<Checkbox label="Email me updates" name="updates" value="yes" />
<Checkbox label="Select all" checked={all} indeterminate={some} onChange={toggleAll} />
<Checkbox label="Remember me" description="Keeps you signed in on this device." defaultChecked />
<Checkbox label="Buy oat milk" strikeWhenChecked checked={done} onChange={setDone} />

onChange receives the new checked boolean. Use checked for controlled and defaultChecked for uncontrolled. name, value, required and disabled are passed to the native input.

Label and description

label is required. An optional description sits below it and is linked with aria-describedby. size is sm, md or lg and tone sets the fill when checked (default accent).

Click space and label toggle

Indeterminate

indeterminate shows a dash and is announced as "mixed". It is a display state only: you decide what the next click does.

Indeterminate is mixed

Checklists

strikeWhenChecked strikes through and mutes the label while the box is checked, and mutes the description with it. It works the same controlled or uncontrolled. A box that is indeterminate is not struck: a partly done task is not done.

Strike when checked by pointer and keyboard

The muted label keeps a contrast of at least 4.5:1 against the surface in light and dark.

Done label is readable in light and dark

Props

Every prop of Checkbox
Prop	What it does	Type	Default
`label`Required	The control's label. Pressing it toggles the control.	`ReactNode`
`indeterminate`	Mixed state (announced as "mixed"), e.g. a partially selected "select all".	`boolean`
`strikeWhenChecked`	Checklist style: while the box is checked, the label is struck through and muted (and the description muted), so a done task reads as done. Not applied while `indeterminate`. Default false.	`boolean`	`false`
`description`	Help text shown under the label and read with the control.	`ReactNode`
`checked`	Controlled: whether it is on.	`boolean`
`defaultChecked`	On at first, when uncontrolled.	`boolean`
`onChange`	Called when the person turns it on or off, with the new state.	`((checked: boolean) => void)`
`name`	Name it is submitted under in a form, when on.	`string`
`value`	The value submitted with `name` when on. The browser sends "on" when this is not set.	`string`
`required`	It must be on for the form to submit.	`boolean`
`disabled`	It cannot be changed and is not submitted with a form.	`boolean`
`size`	Size of the control and its text. Default "md".	`Size`	`"md"`
`tone`	Fill colour when on. Default "accent".	`Tone`	`"accent"`
`id`	Id of the native input; one is generated when not set.	`string`
`className`	Added to the root element (the label that wraps the row), for layout.	`string`
`style`	Layout only, applied to the root element.	`CSSProperties`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Behaviour and accessibility, table 1
Input	Result
Click or tap the box or label	Toggles
`SpaceSpace`	Toggles
`TabTab`	Focus with a visible ring

Forms: values reach FormData, form reset restores the initial state, and required is enforced by the browser.
Whole row: the label and description are part of the click target.
Done style: with strikeWhenChecked the checked state is still what is announced; the strike only shows it. In forced colours the muted colour is dropped and the strike stays, in the system text colour. The colour change is a transition and is switched off under reduced motion.

Touch

The hit area is at least 24px, growing to 44px on coarse pointers without changing the visible size.

Theming

Tokens: --cy-checkbox-size, --cy-checkbox-radius and --cy-checkbox-border. The sm and lg sizes use --cy-checkbox-size-sm and --cy-checkbox-size-lg.

Theming, table 2
Token	Controls
`--cy-checkbox-done-color`	Label and description colour of a checked `strikeWhenChecked` row. Default `--cy-color-muted`. Keep it at 4.5:1 or more against the surface.
`--cy-checkbox-strike-width`	Thickness of the strike. Default: the border width, or 1/16 of the text size when that is larger.

The row around the box is a Choice: the space between box and label is --cy-choice-gap, and the two done tokens above become the row's --cy-choice-done-color and --cy-choice-strike-width.

createTheme({ components: { checkbox: { radius: "50%" } } });

Switch · RadioGroup · Choice · Field

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

Label and descriptionLink to "Label and description"

IndeterminateLink to "Indeterminate"

ChecklistsLink to "Checklists"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

TouchLink to "Touch"

ThemingLink to "Theming"

RelatedLink to "Related"