Checkboxes

View example

Angular

Step 1. Install

Execute the following command to install this component.

npm i [NPM-PLACE-HOLDER]/ds-checkbox

Step 2. Import

Import the following into your app.module.ts file.

import { DsCheckboxModule } from 'ds-checkbox';

Code snippet

<div role="group" aria-labelledby="checkbox-names foo">
    <p id="checkbox-names">Select a checkbox:</p>
    <cpc-ds-checkbox 
        *ngFor="let country of countries; let i=index" 
        formArrayName="selectedCountries" 
        id="country_{{i}}" 
        [text]="country.name" 
        [value]="country.value" 
        [checked]="i !== 2 ? false : true" 
        [disabled]="i === 3 ? true : false" 
        (change)="onCheckboxChange($event)">
    </cpc-ds-checkbox> 
    <div id="foo" class="ds-error">You must select an option</div>
</div>

Properties

Name	Type	Default	Description
id	string	checkbox-id	id for the checkbox. id is the same as the name of the checkbox.
text	string	Checkbox text here	The checkbox label.
value	string	Checkbox value	The checkbox value.
checked	boolean	false	Set the checkbox to checked by using “true”. Use "false" to set the checkbox to not checked.
disabled	boolean	false	Disable the checkbox using “true”. Enable the checkbox using “false”.
(change)	Method		Call a method if you want to capture value to do an action `(change)="onCheckboxChange($event)"`

HTML

Step 1: Import CSS

Import the following in your theme or page.

Step 2: Import JS

<script src="[JS-PLACE-HOLDER]"></script>

Code snippet

<div role="group" aria-labelledby="checkbox-names fooCheckbox">
  <p class="checkbox" id="checkbox-names">Select a checkbox:</p>
  <div class="checkbox-container">
    <input id="oneCheckbox" class="by-keyboard" type="checkbox">
    <label for="oneCheckbox">One</label>
  </div>
 <div class="checkbox-container">
   <input id="twoCheckbox" class="by-keyboard" type="checkbox">
   <label for="twoCheckbox">Two</label>
  </div>
</div>

General guidelines Interaction Accessibility considerations Design specs

General guidelines

A checkbox allows the user to select options without deselecting others. It includes a checkbox icon and a label describing the selection. If the objective is to have the user make one selection, consider using radio buttons.

Positioning

Checkboxes are arranged like lists. Labels for checkbox items always appear to the right of the checkbox.

Stack checkbox items vertically. Horizontally arranged checkboxes are difficult to scan.

Responsive design

If checkbox copy is long and likely to wrap on smaller screens, make sure the copy wraps under the first letter of copy, not the checkbox button. When copy wraps, vertically align checkboxes with the first line of copy.

Interaction

States

The entire checkbox and label area is interactive. Checkboxes can have the following states:

Default:
In this state, a checkbox can be selected by clicking on it.
Selected:
In this state, a checkbox can be deselected by clicking on it.
Focus:
In this state, a checkbox will be surrounded by a blue box and activated by pressing spacebar. This state is critical for users that do not navigate your design by mouse.
Disabled:
In this state checkbox items cannot be selected, deselected, or activate a focus state.

Unselected

Selected

Disabled

Don’t preselect a checkbox unless you’re confident most users would make that selection.

Feedback

Error messages

When there is an error, the message is placed under the last checkbox item.

Accessibility considerations

Keyboard accessibility

Checkbox focus states allow users to navigate checkbox options without a mouse. To provide visibility and context, the focus state should span the entire line, not just the checkbox itself.

The user can navigate checkbox options with tab and toggle between checked and unchecked states using the space bar.

Screen readers

Screen readers should announce the element as a checkbox, its associated label and its state.

With the same header, use <div role=”group”> to group checkboxes. Screen readers will announce the group of checkboxes according to the label you specify.

Though titling checkbox groups using headers or bold text is not necessary for screen readers, remember these elements are particularly useful for visual scanning.

For all screen sizes.

General guidelines Dos and don'ts

General guidelines

A checkbox allows the user to select options without deselecting others. It includes a checkbox and a label describing the selection. If the objective is to have the user make one selection, consider using radio buttons.

Checkboxes are interactive and allow the user to select or deselect with a click. Content appears to the right of checkbox.

When writing for checkboxes, error messages let the user know what’s needed to proceed to complete the task. The error message appears under the last checkbox item.

	Guidelines	Examples
Recommended length	Use as needed to complete the thought but try to keep it to one line	Liability coverage
Line wrap	Minimize but not recommended; checkbox item should wrap under itself and not under the bullet	Signature
Phrasing	Short phrases that explain each item	This is a mobile phone number
Case	Sentence case	I agree with the Terms and Conditions

Send delivery status updates to others

Send Delivery Status Updates to Others

I confirm that my item was not delivered

I confirm that my item was not delivered. I agree that my request is subject to verification by Canada Post, and Canada Post reserves all rights if it determines that this request has been falsely submitted. Other terms and conditions apply.

I’d like to receive email updates on shipping tools.

I don’t want to receive email updates on shipping tools.

Download package

Mendix

Checkboxes are an out-of-the-box functionality.

You simply need to select the Checkbox option from the toolbox on the right.

The styles for Checkboxes should be automatically applied along with the styles for their error states.

The Mendix toolkit can be found here.

Guidelines

Keyboard interaction

When the checkbox has focus:

Space: Changes the state of the checkbox (checked or not checked)
Tab: Focus moves to the next focusable element on the page
Shift + Tab: Focus moves to the previous focusable element on the page

Focus remains on the checkbox once its state is changed.

ARIA properties

The checkbox component can have the following ARIA properties:

There is no need to add the role attribute if using native <input type=”checkbox”/>.
The aria-checked state indication property can be set to "true" when checked and "false" when not checked.
The container can have the role of “group” when checkboxes are grouped together.
The group label and group error text are associated with the container using the aria-labelledby property. This property takes the ID of the group label and group error text as input.

Testing

When testing a checkbox, the tester must ensure:

The checkbox is fully keyboard operable
Indications for focused and the hovered states are clear and prominent
State change (checked/not checked) is clear and doesn't rely on colour alone
The checkbox doesn't cause an instant change and that the user can review the change and save the settings before they take effect
The checkbox has the role of “checkbox”
The screen reader announces the checkbox label, role, and state (checked/not checked)
The screen reader announces the group label and error text (if any) when entering a checkbox group

Checkboxes

Use when:

Interactive component

Library integration

Angular

Step 1. Install

Step 2. Import

Code snippet

Properties

HTML

Step 1: Import CSS

Step 2: Import JS

Code snippet

General guidelines

Positioning

Responsive design

Interaction

States

Unselected

Selected

Disabled

Feedback

Error messages

Accessibility considerations

Keyboard accessibility

Screen readers

Design specs

For all screen sizes.

General guidelines

Dos and don’ts

Upper and lower case

You might also be interested in:

Designers

Developers

Writers

Information architecture

Positive wording

Code Samples

Basic

Angular

Mendix

Best practices

Guidelines

Keyboard interaction

ARIA properties

Testing

Related content