skip to content
menu
components · checkbox
componentsinputsreact implementation

checkbox

A checkbox turns one option on or off in a form that people save later. It can also show a mixed state, for “some of these”.

when to use

  • For an option that is part of a form people save or send: “Include archived items”, “Notify the owner”.
  • For a list of independent options, where any number of them can be on.
  • To select rows in a list or a table, with a mixed box above them for “some selected”. Selection and bulk actions shows how.
  • For one confirmation before a step that destroys something: “Also delete the snapshots”.

when to use something else

  • For a setting that applies the moment it changes. Use a switch. A checkbox reads as part of a form, and it sends people looking for a save button.
  • For one choice out of several that exclude each other. Use a select, or the browser's own radio buttons for two or three choices. Forms and settings has more.
  • To filter a list. Use the filter bar or filter tabs.
  • To start an action. Use a button. A checkbox only records a choice.

anatomy

  1. Clickable area. The box, a small gap and the label text. A click anywhere on it turns the box on or off.
  2. Box. A small square with a thin grey border, on a dark background. When it is on or mixed, it fills with blue.
  3. Mark. A check, or a dash when the box is mixed, in the dark colour of the page. It is hidden from assistive technology: the checkbox's own state carries the meaning.
  4. Label (optional). The option, in the body face.

variants and states

state looks
Off An empty box with a grey border
On Filled with blue, with a check
Mixed Filled with blue, with a dash
Focused An outline just around the box, for keyboard focus only
Disabled Box and label dimmed. It can't take focus, be changed or be sent with the form

A checkbox doesn't change under the pointer, and it has no look for an error.

Group related options under one question. A field labels a single control, so a group goes in a frame of its own: the browser's own frame for a set of options, with a caption that asks the question.

Notify me about

The mixed state marks a parent whose children are partly on. The parent is on when all of its children are on, and mixed when only some of them are.

A box can go without a visible label, as when it selects a table row, as long as it has a name.

behaviour

  • A click on the label text turns the box on or off too.
  • A checkbox is one tab stop, and space turns it on or off. enter doesn't change it.
  • Pressing a mixed parent turns all its children on; the next press turns them all off.

The full keyboard map is on the checkbox's React page.

accessibility

  • It is the browser's own checkbox, so screen readers and the keyboard work with it, and it is sent with the form like any other field. It reports on, off and mixed.
  • Its label names the checkbox, and makes the label's text part of what people can click.
  • A box without a visible label needs a name written for it: its accessible name. Nothing checks for one today, and a box without a name is announced only as “checkbox”. Name what it selects: “select api-7f9c”.
  • The box itself is small. With a label, the whole label is the target. Boxes without a label in a list need enough room from one to the next, so that each target stays separate.

Today:

  • There is no error state. Inside a field with an error, the error text shows, but the box doesn't change.
  • There are no styles for forced colours, the high-contrast setting some operating systems offer.

content

  • Write the label as what is true when the box is on, and keep it positive: “Send a weekly summary”, not “Don't send a weekly summary”.
  • Keep it short, in sentence case, with no full stop. A checkbox label is in the body face: the reader's language.
  • In a group, start the options the same way, so they read as answers to the group's question.
  • A mixed parent names the whole set: “All volumes”, “Back up all volumes”.
  • A row's box has no visible label, so its name says which row it selects: “select worker-2”.

do and don't

do
Positive: on means it happens.
don't
A negative label turns off into a double negative.
do
A setting that applies at once is a switch.
don't
A checkbox reads as part of a form: people wait for a save button that isn't there.
do
Notify me about
The group's caption asks the question; the options answer it.
don't
Options without a question: notify, hide, or archive? Screen readers have no name for the group either.

specs

part spec
Clickable area A <label> element around the box and the label text, 8px apart; a click anywhere on it toggles the box. The native checkbox lies over the box, transparent, and takes the focus, the clicks and the form value.
Box 16 × 16px, border-radius: 0, a 1px --border-control border on --bg-2. On or mixed: a --cloud-blue fill and border.
Mark A 12px check, or a dash when mixed, in --bg; hidden from assistive technology (aria-hidden). The native state carries the meaning.
Label label. Inter 13px, line height 1.4, --fg-2.
state in code looks
Off The default An empty box, --border-control border
On checked, or defaultChecked --cloud-blue fill, with a check
Mixed indeterminate --cloud-blue fill, with a dash
Focused :focus-visible A 2px --focus-ring outline, 1px around the box, on keyboard focus only
Disabled disabled Box and label at 50% opacity, a not-allowed cursor. It can't be focused, changed or submitted.
  • No visible label: name the box with aria-label or aria-labelledby, such as aria-label="select api-7f9c". Nothing enforces it today.
  • Target: with a label, the whole label. Boxes without a label in a list need at least 24px from one to the next.
  • Group: a native <fieldset> whose <legend> asks the question; a Field labels a single control.
  • Motion: the fill, border and mark colours change in 120ms ease.