Skip to main content

Checkbox

The Checkbox element is a control that is checked (ticked) when activated, like you might see in an official government paper form. A checkbox allows you to select single values for submission in a form (or not).

— Definition from the MDN web docs

Checkbox vs. switch​

Checkboxes and Switches have similar purposes and must be used consistently across your application.

As a rule of thumb, checkboxes store status, whereas switches have an immediate effect (like a light switch in the real world). Checkboxes allow users to change their minds before submitting their choices.

Use checkboxes:

  • when the primary target platform is the desktop
  • to let the user select any number of options from a list
  • when the effect of checking the box is not immediate

Watch this NNGroup video for examples and additional resources.

Checkbox vs. radio​

Use radio buttons when there is a list of two or more options that are mutually exclusive, and the user must select exactly one choice.

Use checkboxes when there are lists of options, and the user may select any number of choices, including zero, one, or several.

Radios always have a default selection, whereas checkboxes often default to having none of the options selected.

See this NNGroup article for an in-depth discussion about those differences.

Text​

The text property sets the label displayed on the checkbox:

Loading...
Live Editor
<qds-checkbox text="Select me"></qds-checkbox>

Text is optional but highly recommended. In Figma, disable the 🅵 text toggle to hide the label.

Loading...
Live Editor
<div class="qds-controls qds-related flex-row">
  <qds-checkbox></qds-checkbox>
  <qds-checkbox></qds-checkbox>
  <qds-checkbox></qds-checkbox>
</div>

Writing guidelines​

  • Use positive and active wording for the label so that it's clear what will happen if the user turns on the checkbox
  • Keep labels short to make them scannable

Checked​

Use the checked attribute to activate the checkbox. Clicking on a checked box will uncheck it.

Loading...
Live Editor
<qds-checkbox checked text="Checked"></qds-checkbox>

Use checkboxes only to change settings, not as action buttons that make something happen. Also, the changed settings should not take effect until the user clicks the confirmation button.

Size​

Checkboxes follow the transversal control size principles. Use the standard size unless you're in one of the specific contexts described on that page.

Loading...
Live Editor
<div class="qds-controls qds-related">
  <label class="qds-controls qds-related flex flex-row">
    <qds-label text="Standard size:"></qds-label>
    <qds-checkbox text="Select me"></qds-checkbox>
  </label>
  <label class="qds-controls-large qds-related flex flex-row">
    <qds-label size="large" text="Large size:"></qds-label>
    <qds-checkbox size="large" text="Select me"></qds-checkbox>
  </label>
  <label class="qds-controls-small qds-related flex flex-row">
    <qds-label size="small" text="Small size:"></qds-label>
    <qds-checkbox size="small" text="Select me"></qds-checkbox>
  </label>
</div>

Layout​

Stacking​

Lay out your checkboxes vertically, using the related controls spacing amount between them, and add a <qds-label> to introduce the group:

Loading...
Live Editor
<div class="qds-controls qds-related">
  <qds-label required text="Choose one more more options:"></qds-label>
  <qds-checkbox text="Option 1"></qds-checkbox>
  <qds-checkbox text="Option 2"></qds-checkbox>
  <qds-checkbox text="Option 3"></qds-checkbox>
</div>

Visually present groups of choices as groups and clearly separate them from other groups on the same page:

Loading...
Live Editor
<div class="qds-controls">
  <div class="qds-controls qds-related">
    <qds-label required text="Your favorite ice cream flavors:"></qds-label>
    <qds-checkbox name="ice-cream-flavor" text="Chocolate"></qds-checkbox>
    <qds-checkbox name="ice-cream-flavor" text="Coconut"></qds-checkbox>
    <qds-checkbox name="ice-cream-flavor" text="Mint"></qds-checkbox>
    <qds-checkbox name="ice-cream-flavor" text="Strawberry"></qds-checkbox>
    <qds-checkbox name="ice-cream-flavor" text="Vanilla"></qds-checkbox>
  </div>
  <div class="qds-controls qds-related">
    <qds-label required text="Your favorite vegetables:"></qds-label>
    <qds-checkbox name="vegetable" text="Bean"></qds-checkbox>
    <qds-checkbox name="vegetable" text="Tomato"></qds-checkbox>
    <qds-checkbox name="vegetable" text="Spinach"></qds-checkbox>
  </div>
</div>

Inlining​

Avoid displaying several checkboxes on the same line.

Set the inline attribute to let the checkbox's label align nicely with siblings' labels:

Loading...
Live Editor
<div class="qds-controls qds-related flex-row justify-between">
  <qds-checkbox inline text="Remember my choice"></qds-checkbox>
  <div class="qds-controls qds-related flex-row">
    <qds-button importance="emphasized" text="Save"></qds-button>
    <qds-button text="Don't save"></qds-button>
  </div>
</div>

If the checkbox label is too long, it will span over multiple lines, but its baseline will remain aligned with the other controls:

Loading...
Live Editor
<div class="qds-controls qds-related flex-row">
  <qds-button text="Button"></qds-button>
  <qds-checkbox inline text="This is a very long label that will span over multiple lines depending on how much space is available on the screen"></qds-checkbox>
  <qds-button text="Button"></qds-button>
</div>

In forms​

Follow the Forms design pattern guidelines to properly organize and space your form labels and controls.

Additional options​

Indeterminate​

Use the indeterminate attribute to make the checkbox indeterminate. Clicking on an indeterminate box will set it to checked.

The indeterminate state is useful in the context of a checkbox hierarchy:

Loading...
Live Editor
<div class="qds-controls qds-related">
  <qds-checkbox indeterminate text="Parent option"></qds-checkbox>
  <div class="qds-controls qds-related qds-tree-indent">
    <qds-checkbox checked text="Option 1"></qds-checkbox>
    <qds-checkbox text="Option 2"></qds-checkbox>
    <qds-checkbox checked text="Option 3"></qds-checkbox>
    <qds-checkbox text="Option 4"></qds-checkbox>
    <qds-checkbox text="Option 5"></qds-checkbox>
  </div>
</div>

Note: Quartz does not provide any logic that links the parent checkbox's status to its children.

Required​

Set the required attribute on the checkbox to display a red asterisk next to its label. If the user does not check the box, the form will display an error:

Loading...
Live Editor
<form class="qds-controls qds-related">
  <qds-checkbox required text="I agree to the terms"></qds-checkbox>
  <qds-button text="Submit"></qds-button>
</form>

Disabled​

Use the disabled attribute to disable the checkbox. Clicks will be suppressed until the disabled state is removed.

Loading...
Live Editor
<qds-checkbox disabled text="Disabled"></qds-checkbox>

Implementation tips​

Importing​

Note: if you're using the lazy loader to load Quartz components, you can ignore this section.

To import this component from the public jsDeliver CDN using a JavaScript import:

import { defineCustomElementQdsCheckbox } from 'https://cdn.jsdelivr.net/npm/@quartzds/core@next+esm'
defineCustomElementQdsCheckbox()

Component reference​

Properties​

Attribute / PropertyTypeDescriptionDefault
autofocus / autoFocus
boolean | undefined

Specify whether the checkbox should have focus when the page loads.

undefined
checked
boolean | undefined

Sets the checkbox's state.

undefined
disabled
boolean | undefined

Prevents the checkbox from being interacted with: it cannot be pressed or focused.

undefined
form
HTMLFormElement | null | string

The <form> element to associate the checkbox with (its form owner).

The value of this attribute must be the id of a <form> in the same document. If this attribute is not set, the <qds-checkbox> is associated with its ancestor <form> element, if any.

This attribute lets you associate <qds-checkbox> elements to <form>s anywhere in the document, not just inside a <form>. It can also override an ancestor <form> element.

null
indeterminate
boolean | undefined

Sets the checkbox to an indeterminate state. This is usually applied to checkboxes that represent a "select all/none" behavior when associated checkboxes have a mix of checked and unchecked states.

undefined
inline
boolean

Adds vertical margin to the checkbox for alignment.

This is useful when creating inline layouts so that the first lines have the correct vertical centering.

false
name
string | undefined

The name of the checkbox, which is submitted with the form data.

undefined
required
boolean | undefined

A value must be specified for the checkbox before the owning form can be submitted.

See Client-side validation and the HTML attribute: required for more information.

undefined
size
"large" | "small" | "standard" | undefined

The checkbox's size.

'standard'
text
string | undefined

The checkbox's text.

undefined
validation-message / validationMessage
string

The error message that would be shown to the user if the <qds-checkbox> was to be checked for validity.

''
ValidityState

The ValidityState object for this <qds-checkbox>.

VALID_STATE
value
null | number | string | undefined

The value of the checkbox, submitted as a name/value pair with form data.

'on'
will-validate / willValidate
boolean

True if <qds-checkbox> will be validated when the form is submitted; false otherwise.

false

Events​

EventTypeDescriptionBubblesCancelableComposedqdsBlur
{ readonly relatedTarget: EventTarget | null; }

Emitted when the checkbox loses focus.

qdsChange
void

Emitted when a change to the checkbox's state is committed by the user.

qdsFocus
{ readonly relatedTarget: EventTarget | null; }

Emitted when the checkbox gains focus.

Last updated on