Proximus design systemDevPlease don't forget to read Usage part of each element.
Checkboxes
expiry date: 30/09/2021
Checkboxes allow the user to select/deselect one or multiple items in a list of options.
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.
Do
Do use radio buttons when only one item can be selected.
Don't
Don't use checkboxes when only one item can be selected.
Forms can be simple or complex, so we have prepared clear recommendations for you to use. These guidelines will help you build your forms and maintain consistency between all the forms of our digital platforms. Discover our recommandations to build a form.
States
-
Default state - Unchecked
State visible when no option checked. -
Hover/Focused state
State visible when the cursor hovers the button and triggered by keyboard navigation or click. Cursor becomes a pointer. -
Checked state
State visible with option is checked. -
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. -
Read only state
State visible if the checkbox is checked but not clickable. -
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
Do
When maximum number of checkboxes to select is reached by the user, do set the others checkboxes on disabled state.
Don't
When maximum number of checkboxes to select is reached by the user, don't set the others checkboxes on error state.
Anatomy
-
Legend (optional)
Communicates what needs to be selected below. -
Input
A checkbox input indicating the appropriate state. By default it is unselected. -
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.
Do
Vertically stacked
Don't
Horizontally stacked
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
- Make the label selectable. Users should be able to tap on or click on either the text label or the checkbox to select or deselect an option.
- 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.
Do
Do let text wrap beneath the checkbox so the control and label are top aligned.
Don't
Don't vertically center wrapped text with the checkbox.
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.
-
Checking the parent checkbox automatically selects all of the nested children checkboxes. Unchecking the parent checkbox automatically deselects all of the children checkboxes.
-
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.
To prevent complex architecture and overwhelming number of checkboxes. Avoid using nest more than one level of checkboxes
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
Group of checkboxes must be wrapped in a <fieldset>
containing a <legend>
for the title.
If the title is not visually needed, <legend>
can be hidden and showed only for screen reader with show-for-sr
class.
Single checkbox must make sense from its label. Single checkbox can't have <fieldset>
as the fieldset is only use to group elements. A group with a single element doesn't make sense.
We put ac-
prefix (abbreviation for "accessibility") to know that this id
has been added for accessibility matter.
Default Checkbox
Each <input>
must be wrapped within <div class="rs-checkbox">
container.
<fieldset>
must have rs-form-item
class.
By default, all form fields are mandatory, except those mentioned with (optional) in the label.
Default checkbox with displayed legend
Default checkbox with stylized legend
Negative Default Checkbox
rs-form-neg
class added on <form>
or a <div>
container (if <form>
is not needed in particular cases like with Angular) allows to switch all form fields to negative version.
Disabled Checkbox
Just add disabled
attribute to the <input>
.
Unchecked
Checked
Negative
Error Checkbox
To use Zurb Foundation form check javascript, data-abide="ajax"
attribute should be added to <form>
so error class will be added/removed dynamically when needed, for example if <input>
is required.
The error message <span>
should have an id
(prefixed with "ac-" as accessibility abbreviation to know this is added for accessibility matter) which should be referenced in the <input aria-describedby="error_id">
for screen readers when the error is displayed. This is automatically added by the javascript.
Negative
Indeterminate Checkbox
Sometimes you may need a list of checkbox with a parent checkbox. If not all the checkbox inside the list aren't checked, the checkbox has the indeterminate state.
Indeterminate checkbox is a webcomponent which needs data-rslib-webcomponent-load="rslib.apps.checkboxlist" attribute to work.
<input type="checkbox">
has an aria-checked
set to "mixed" if not all the checkboxes linked to it are checked, to "true" if all the checkboxes are checked and "false" if none of them is checked.
An aria-controls
is added to the same <input>
with the id of all checkboxes linked to it. This attribute is mandatory to run the javascript!
Nested lists
Negative
Disabled
JavaScript
Each time you add form element to the page, you have to use this JS function
As Indeterminate checkbox is a webcomponent, you will have to load
Next time you add Indeterminate checkbox to the page, you also have to call this JS:
CONTEXT refers to document or html element parent.
Indeterminate checkboxes
The <fieldset>
tag must have data-checkbox-list-fieldset
attribute to run the javascript.
The input[type="checkbox"]
parent list must have data-checkbox-list-parent
attribute.
And finally the <ul>
tag must have data-checkbox-list-children
with the id
of the input
parent.
Deprecated
The checkbox below is not accessible and should no longer be used.
This element will no longer be available from the expiry date meaning the related css will be removed and the element design will be broken if it's not adapted to the new html.
Class:
-
rs-label-checkbox -
rs-label -
label.rs-checkbox -
rs-mandatory -
rs-checkbox-big -
rs-checkbox-big-standalone -
rs-input-info
Big checkboxes
Normal state:
Disabled state:
Error state:
Standalone in a panel:
Standalone & disabled in a panel:
Standalone & error in a panel:
Configuration metadata (DSCheckboxComponent)
Selector: ds-checkbox
Class: DSCheckboxComponent
Use case example
NOT AVAILABLE LIVE PREVIEW
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
NOT AVAILABLE LIVE PREVIEW
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',
}