Checkboxes

Overview

Checkboxes are used when there are multiple items to select in a list. Users can select zero, one, or any number of items. Each checkbox works independently from other checkboxes in the list. The default view of a set of checkboxes is having no option selected.

When to use

• In forms on a full page, in overlayers,...
• To provide a valid way to digitally agree or sign contracts
• To filter data either on a page, in a menu, or within a component.

When not to use

If a user can select only one option from a list, radio buttons should be used instead of checkboxes. Checkboxes allow the user to select multiple items in a set whereas radio buttons allow the user to select only one option.

---

States

1. Default state - Unchecked
   State visible when no option checked.
2. Hover/Focused state
   State visible when the cursor hovers the button and triggered by keyboard navigation or click. Cursor becomes a pointer.
3. Checked state
   State visible with option is checked.
4. Disabled state
   State visible if the checkbox is not clickable. All elements are displayed but they are greyed out in order to signify the change of state.
5. Read only state
   State visible if the checkbox is checked but not clickable.
6. Error state
   State visible when a checkbox should be checked and it’s not the case (e.g. License Agreement acceptance). All elements are displayed in another colour in order to signify the error state.

A checked input should never have the error state

---

Anatomy

1. Legend (optional)
   Communicates what needs to be selected below.
2. Input
   A checkbox input indicating the appropriate state. By default it is unselected.
3. Label
   Labels indicates the option(s) that will be selected when clicked.

---

Alignment

Checkbox labels are positioned to the right of their inputs. If there is a checkbox grouping, they are laid out vertically. Vertical listings are easier for the reader to identify which checkbox is related to which label.

---

Content

Legend

• If necessary, a legend can accompany a set of checkboxes to provide further context or clarity.
• A group label (legend) can either state the category of the grouping or describe what actions to take below.
• Regardless of whether the label is visible in the interface, a group label is always needed in code as from 2 checkboxes. See the checkbox code tab for more information.

Label

• Always use clear and concise labels for checkboxes.
• Be explicit about the results that will follow if the checkbox is selected.
• Labels appear to the right of checkbox inputs.
• We recommend checkbox labels being fewer than three words.
• Do not truncate checkbox label text with an ellipsis.

---

Lists with sub-selections

Nesting

Checkboxes can be nested when a parent and child relationship is needed. Users can either select an entire set of options or only a subset.

1. Checking the parent checkbox automatically selects all of the nested children checkboxes. Unchecking the parent checkbox automatically deselects all of the children checkboxes.

2. Checking a child checkbox, if at least one other child checkbox is not selected, automatically puts the parent checkbox into the indeterminate state. Unchecking a child checkbox, when all other children checkboxes remain selected, switches the parent checkbox from the default checked state to the indeterminate state.

Indeterminate state

Use the indeterminate state when the checkbox contains a sublist of selections, some of which are selected.

---

Related elements

Checkboxes vs. radio buttons

Whereas radio buttons represent a group of mutually exclusive choices, users can select one or more checkboxes from a group. In use cases where only one selection of a group is allowed, use the radio button component instead of the checkbox.
More info about radio buttons

Checkboxes vs. switch

Generally, toggle switches are preferred when the resulting action will be instantaneously applied, without the need for further confirmation. Checkboxes generally represent one input in a larger flow which requires a final confirmation step.
More info about switch

Checkboxes vs. selectable boxes

Selectable boxes allow the user to select unique or multiple options.
More info about selectable boxes

Sizes and colors

Configuration metadata (DSCheckboxComponent)

Selector: ds-checkbox

Class: DSCheckboxComponent

Use case example

Inputs

Name	Type	Default	Required	Description
id	string	undefined	Yes	Unique id of the checkbox
error	boolean	false	No	Condition to show/hide error message
errorMessage	string	null	No	Error message text
label	string	null	Yes	Checkbox label
negative	boolean	false	No	Defines light/dark style of the component
required	boolean	false	No	Defines if the control is required/optional
name	string	undefined	No	Defines the name attribute of the input
dataCy	string	undefined	No	Defines the automation test data-cy attribute

Outputs

None

Models

None

---

Configuration metadata (DSCheckboxesComponent)

Selector: ds-checkboxes

Class: DSCheckboxesComponent

Use case example

Inputs

Name	Type	Default	Required	Description
config	ICheckboxesConfig	[]	Yes	Unique id of the checkbox
error	boolean	false	No	Condition to apply or not the error CSS class

Outputs

None

Models

        export interface ICheckboxesConfig {
            checkValues?: ICheckValue[];
            required?: boolean;
            legend?: string;
            negative?: boolean;
            disabled?: boolean;
            errorMessage?: string;
            nested?: INestedCheckbox;
        }

        export interface ICheckValue {
            id?: string;
            label: string;
            checked?: boolean;
            disabled?: boolean;
        }

        export interface INestedCheckbox {
            nestType: NestedEnum;
            parents: INestedCheckValues[];
        }

        export interface INestedCheckValues {
            label: string;
            id?: string;
            children?: INestedCheckValues[];
            childIds?: string;
            checked?: boolean;
        }

        export enum NestedEnum {
            Mixed = 'mixed',
            True = 'true',
            False = 'false',
        }