Checkboxes
Overview
Use checkboxes to let the user select one or more options from a list.
Example Checkboxes contents
Nunjucks
{% from "components/question/_macro.njk" import onsQuestion %}
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{%
call onsQuestion({
"title": "What devices do you own?",
"legendIsQuestionTitle": true,
"classes": "ons-u-mt-no"
})
%}
{{
onsCheckboxes({
"checkboxesLabel": "Select all that apply",
"dontWrap": true,
"name": "devices",
"checkboxes": [
{
"id": "mobile-phone-example",
"label": {
"text": "Mobile phone"
},
"value": "mobile-phone"
},
{
"id": "tablet-example",
"label": {
"text": "Tablet"
},
"value": "tablet"
},
{
"id": "laptop-example",
"label": {
"text": "Laptop"
},
"value": "laptop"
},
{
"id": "desktop-example",
"label": {
"text": "Desktop computer"
},
"value": "desktop"
}
]
})
}}
{% endcall %}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<div class="ons-question ons-u-mb-xl ons-u-mt-no">
<div class="ons-question__answer ons-u-mb-l">
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend ons-u-mb-no">
<h1 id="fieldset-legend-title" class="ons-fieldset__legend-title">What devices do you own?</h1>
</legend>
<div class="ons-input-items">
<p class="ons-checkboxes__label"> Select all that apply </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="mobile-phone-example" class="ons-checkbox__input ons-js-checkbox"
value="mobile-phone" />
<label class=" ons-checkbox__label" for="mobile-phone-example" id="mobile-phone-example-label">Mobile
phone</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="tablet-example" class="ons-checkbox__input ons-js-checkbox" value="tablet" />
<label class=" ons-checkbox__label" for="tablet-example" id="tablet-example-label">Tablet</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="laptop-example" class="ons-checkbox__input ons-js-checkbox" value="laptop" />
<label class=" ons-checkbox__label" for="laptop-example" id="laptop-example-label">Laptop</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="desktop-example" class="ons-checkbox__input ons-js-checkbox" value="desktop" />
<label class=" ons-checkbox__label" for="desktop-example" id="desktop-example-label">Desktop
computer</label>
</span>
</span>
</div>
</div>
</fieldset>
</div>
</div>When to use this component
Use the checkboxes component when you need to help users select multiple options from a list.
When not to use this component
Do not use the checkboxes component if users can only choose one option from a list. In this case, use the radios component.
How to use this component
Checkboxes are grouped within a fieldset which starts with a <legend> which lets the user know what they need to do.
Variants
Descriptions
This variant allows you to add more context to the checkbox answers. The description is added by providing a description parameter within the checkbox’s label parameter.
Answer descriptions are a good way to provide examples to help a user answer a question without disrupting their journey through the survey.
Answer descriptions should:
- be short – try to have no more than 100 characters
- be clearly written
- be relevant to that answer only, not any of the other answers
- start with a capital letter
- not have a full stop on the end
Example Checkboxes With Descriptions contents
Nunjucks
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{% from "components/question/_macro.njk" import onsQuestion %}
{%
call onsQuestion({
"title": "What type of central heating does your accommodation have?",
"classes": "ons-u-mt-no",
"legendIsQuestionTitle": true
})
%}
{{
onsCheckboxes({
"checkboxesLabel": "Select all that apply",
"dontWrap": true,
"name": "central-heating",
"checkboxes": [
{
"id": "none-checkbox-with-description",
"label": {
"text": "No central heating"
},
"name": "none"
},
{
"id": "mains-gas-checkbox-with-description",
"label": {
"text": "Gas",
"description": "Including tank or bottled gas"
},
"name": "mains-gas"
},
{
"id": "electric-checkbox-with-description",
"label": {
"text": "Electric",
"description": "Including storage headers"
},
"name": "electric"
},
{
"id": "oil-checkbox-with-description",
"label": {
"text": "Oil"
},
"name": "oil"
},
{
"id": "wood-checkbox-with-description",
"label": {
"text": "Wood",
"description": "For example, logs, waste wood or pellets"
},
"name": "wood"
},
{
"id": "solid-fuel-checkbox-with-description",
"label": {
"text": "Solid fuel",
"description": "For example, coal"
},
"name": "solid-fuel"
},
{
"id": "renewable-checkbox-with-description",
"label": {
"text": "Renewable energy",
"description": "For example, solar thermal or heat pumps"
},
"name": "renewable"
}
]
})
}}
{% endcall %}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<div class="ons-question ons-u-mb-xl ons-u-mt-no">
<div class="ons-question__answer ons-u-mb-l">
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend ons-u-mb-no">
<h1 id="fieldset-legend-title" class="ons-fieldset__legend-title">What type of central heating does your
accommodation have?</h1>
</legend>
<div class="ons-input-items">
<p class="ons-checkboxes__label"> Select all that apply </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="none-checkbox-with-description" class="ons-checkbox__input ons-js-checkbox"
value="" name="none" />
<label class=" ons-checkbox__label" for="none-checkbox-with-description"
id="none-checkbox-with-description-label">No central heating</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="mains-gas-checkbox-with-description"
class="ons-checkbox__input ons-js-checkbox" value="" name="mains-gas" />
<label class=" ons-checkbox__label ons-label--with-description" for="mains-gas-checkbox-with-description"
aria-describedby="mains-gas-checkbox-with-description-label-description-hint"
id="mains-gas-checkbox-with-description-label">Gas <span class="ons-label__aria-hidden-description"
aria-hidden="true">
<span class="ons-label__description ons-checkbox__label--with-description">Including tank or bottled
gas</span></span></label>
<span class="ons-label__visually-hidden-description ons-u-vh"
id="mains-gas-checkbox-with-description-label-description-hint">Including tank or bottled gas</span>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="electric-checkbox-with-description" class="ons-checkbox__input ons-js-checkbox"
value="" name="electric" />
<label class=" ons-checkbox__label ons-label--with-description" for="electric-checkbox-with-description"
aria-describedby="electric-checkbox-with-description-label-description-hint"
id="electric-checkbox-with-description-label">Electric <span class="ons-label__aria-hidden-description"
aria-hidden="true">
<span class="ons-label__description ons-checkbox__label--with-description">Including storage
headers</span></span></label>
<span class="ons-label__visually-hidden-description ons-u-vh"
id="electric-checkbox-with-description-label-description-hint">Including storage headers</span>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="oil-checkbox-with-description" class="ons-checkbox__input ons-js-checkbox"
value="" name="oil" />
<label class=" ons-checkbox__label" for="oil-checkbox-with-description"
id="oil-checkbox-with-description-label">Oil</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="wood-checkbox-with-description" class="ons-checkbox__input ons-js-checkbox"
value="" name="wood" />
<label class=" ons-checkbox__label ons-label--with-description" for="wood-checkbox-with-description"
aria-describedby="wood-checkbox-with-description-label-description-hint"
id="wood-checkbox-with-description-label">Wood <span class="ons-label__aria-hidden-description"
aria-hidden="true">
<span class="ons-label__description ons-checkbox__label--with-description">For example, logs, waste
wood or pellets</span></span></label>
<span class="ons-label__visually-hidden-description ons-u-vh"
id="wood-checkbox-with-description-label-description-hint">For example, logs, waste wood or
pellets</span>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="solid-fuel-checkbox-with-description"
class="ons-checkbox__input ons-js-checkbox" value="" name="solid-fuel" />
<label class=" ons-checkbox__label ons-label--with-description" for="solid-fuel-checkbox-with-description"
aria-describedby="solid-fuel-checkbox-with-description-label-description-hint"
id="solid-fuel-checkbox-with-description-label">Solid fuel <span
class="ons-label__aria-hidden-description" aria-hidden="true">
<span class="ons-label__description ons-checkbox__label--with-description">For example,
coal</span></span></label>
<span class="ons-label__visually-hidden-description ons-u-vh"
id="solid-fuel-checkbox-with-description-label-description-hint">For example, coal</span>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="renewable-checkbox-with-description"
class="ons-checkbox__input ons-js-checkbox" value="" name="renewable" />
<label class=" ons-checkbox__label ons-label--with-description" for="renewable-checkbox-with-description"
aria-describedby="renewable-checkbox-with-description-label-description-hint"
id="renewable-checkbox-with-description-label">Renewable energy <span
class="ons-label__aria-hidden-description" aria-hidden="true">
<span class="ons-label__description ons-checkbox__label--with-description">For example, solar thermal
or heat pumps</span></span></label>
<span class="ons-label__visually-hidden-description ons-u-vh"
id="renewable-checkbox-with-description-label-description-hint">For example, solar thermal or heat
pumps</span>
</span>
</span>
</div>
</div>
</fieldset>
</div>
</div>Select and unselect all checkboxes
This variant lets the user select and unselect all checkboxes using a button.
Use the parameter autoSelect with the required child parameters selectAllText, unSelectAllText and context. The context parameter is used for visually hidden text to help screen reader users understand the purpose of the button, for example, "Select all following options".
The "select/unselect all" button cannot be used when one of the checkboxes uses the other parameter to reveal nested inputs. It can however, be inside the other parameter to select and unselect all nested checkboxes or radios.
Example Checkboxes With Select All Button contents
Nunjucks
{% from "components/question/_macro.njk" import onsQuestion %}
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{%
call onsQuestion({
"title": "What devices do you own?",
"legendIsQuestionTitle": true,
"classes": "ons-u-mt-no"
})
%}
{{
onsCheckboxes({
"checkboxesLabel": "Select all that apply",
"dontWrap": true,
"name": "devices",
"autoSelect": {
"selectAllText": "Select all",
"unselectAllText": "Unselect all",
"context": "following checkboxes"
},
"checkboxes": [
{
"id": "mobile-phone-example-checkbox-with-select-all-button",
"label": {
"text": "Mobile phone"
},
"value": "mobile-phone"
},
{
"id": "tablet-example-checkbox-with-select-all-button",
"label": {
"text": "Tablet"
},
"value": "tablet"
},
{
"id": "laptop-example-checkbox-with-select-all-button",
"label": {
"text": "Laptop"
},
"value": "laptop"
},
{
"id": "desktop-example-checkbox-with-select-all-button",
"label": {
"text": "Desktop computer"
},
"value": "desktop"
}
]
})
}}
{% endcall %}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<div class="ons-question ons-u-mb-xl ons-u-mt-no">
<div class="ons-question__answer ons-u-mb-l">
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend ons-u-mb-no">
<h1 id="fieldset-legend-title" class="ons-fieldset__legend-title">What devices do you own?</h1>
</legend>
<div class="ons-input-items">
<p class="ons-checkboxes__label"> Select all that apply </p>
<button type="submit" class="ons-btn ons-u-mb-s ons-js-auto-selector ons-btn--small ons-btn--secondary"
data-unselect-all="Unselect all" data-select-all="Select all">
<span class="ons-btn__inner"><span class="ons-btn__text"><span class="ons-js-button-text">Select
all</span><span class="ons-u-vh"> following checkboxes</span></span></span>
</button>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="mobile-phone-example-checkbox-with-select-all-button"
class="ons-checkbox__input ons-js-checkbox" value="mobile-phone" />
<label class=" ons-checkbox__label" for="mobile-phone-example-checkbox-with-select-all-button"
id="mobile-phone-example-checkbox-with-select-all-button-label">Mobile phone</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="tablet-example-checkbox-with-select-all-button"
class="ons-checkbox__input ons-js-checkbox" value="tablet" />
<label class=" ons-checkbox__label" for="tablet-example-checkbox-with-select-all-button"
id="tablet-example-checkbox-with-select-all-button-label">Tablet</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="laptop-example-checkbox-with-select-all-button"
class="ons-checkbox__input ons-js-checkbox" value="laptop" />
<label class=" ons-checkbox__label" for="laptop-example-checkbox-with-select-all-button"
id="laptop-example-checkbox-with-select-all-button-label">Laptop</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="desktop-example-checkbox-with-select-all-button"
class="ons-checkbox__input ons-js-checkbox" value="desktop" />
<label class=" ons-checkbox__label" for="desktop-example-checkbox-with-select-all-button"
id="desktop-example-checkbox-with-select-all-button-label">Desktop computer</label>
</span>
</span>
</div>
</div>
</fieldset>
</div>
</div>Mutually exclusive checkbox
Use the mutually exclusive variant to let a user give a contrasting answer to the other options provided.
This macro is called automatically when the mutuallyExclusive parameter is set, which adds the:
- mutually exclusive checkbox
- required aria-live alert markup
- classes required for the JavaScript to run
Example Mutually Exclusive Checkboxes contents
Nunjucks
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{% from "components/question/_macro.njk" import onsQuestion %}
{%
call onsQuestion({
"title": "What type of central heating do you have?",
"legendIsQuestionTitle": true
})
%}
{{
onsCheckboxes({
"id": "central-heating-answers",
"dontWrap": true,
"checkboxesLabel": "Select all that apply",
"name": "mutually-exclusive",
"checkboxes": [
{
"id": "gas-example-mutually-exclusive-checkbox",
"label": {
"text": "Gas"
},
"value": "gas"
},
{
"id": "electric-example-mutually-exclusive-checkbox",
"label": {
"text": "Electric"
},
"value": "electric"
},
{
"id": "solid-fuel-example-mutually-exclusive-checkbox",
"label": {
"text": "Solid fuel"
},
"value": "solid-fuel"
},
{
"id": "other-fuel-example-mutually-exclusive-checkbox",
"label": {
"text": "Other"
},
"value": "other",
"other": {
"id": "other-fuel-textbox-example-mutually-exclusive-checkbox",
"name": "other-fuel-answer",
"label": {
"text": "Please specify"
}
}
}
],
"mutuallyExclusive": {
"or": "Or",
"deselectMessage": "Selecting this will uncheck all other checkboxes",
"deselectGroupAdjective": "deselected",
"deselectExclusiveOptionAdjective": "deselected",
"exclusiveOptions": [
{
"id": "no-central-heating-example-mutually-exclusive-checkbox",
"label": {
"text": "No central heating"
},
"attributes": {
"data-attribute": "Example attribute"
},
"value": "no-central-heating"
}
]
}
})
}}
{% endcall %}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to apply to the fieldset |
| legend | string | true (unless legendIsQuestionTitle is set) | Text for the fieldset’s legend |
| legendClasses | string | false | Classes to apply to the legend element |
| legendIsQuestionTitle | boolean | true (unless legend is set) | Creates an h1 inside the legend. Use when there is only a single fieldset on the page |
| description | string | false | Description for the fieldset |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| exclusiveOptions | Array<Checkbox> or Array<radio> | true | Configuration for the mutually exclusive options |
| or | string | false | Text for the “Or” label that separates the mutually exclusive checkbox from the answer options, defaults to "Or". |
| deselectMessage | string | true | The text the aria-live alert will announce to warn that selecting the exclusive checkbox will clear or unselect all other answer options. For example, ”Selecting this will uncheck all other checkboxes”. |
| deselectGroupAdjective | string | true | The text the aria-live alert will announce when an answer option is cleared or unselected when the mutually exclusive checkbox is selected |
| deselectExclusiveOptionAdjective | string | true | The text the aria-live alert will announce when an option is cleared or unselected when the mutually exclusive checkbox is selected |
| error | Error (ref) | false | Configuration for validation errors |
| dontWrap | boolean | false | Prevents fields,checkboxes,date input,duration,input and Textarea from being wrapped in a fieldset component |
| autosuggestresults | string | false | Shows suggested options to users as they enter something into an input field |
HTML
<div class="ons-question ons-u-mb-xl">
<div class="ons-question__answer ons-u-mb-l">
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend ons-u-mb-no">
<h1 id="fieldset-legend-title" class="ons-fieldset__legend-title">What type of central heating do you have?</h1>
</legend>
<div class="ons-input-items">
<div class="ons-js-mutually-exclusive ons-mutually-exclusive">
<p class="ons-checkboxes__label"> Select all that apply </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="gas-example-mutually-exclusive-checkbox"
class="ons-checkbox__input ons-js-checkbox ons-js-exclusive-group-item" value="gas" />
<label class=" ons-checkbox__label" for="gas-example-mutually-exclusive-checkbox"
id="gas-example-mutually-exclusive-checkbox-label">Gas</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="electric-example-mutually-exclusive-checkbox"
class="ons-checkbox__input ons-js-checkbox ons-js-exclusive-group-item" value="electric" />
<label class=" ons-checkbox__label" for="electric-example-mutually-exclusive-checkbox"
id="electric-example-mutually-exclusive-checkbox-label">Electric</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="solid-fuel-example-mutually-exclusive-checkbox"
class="ons-checkbox__input ons-js-checkbox ons-js-exclusive-group-item" value="solid-fuel" />
<label class=" ons-checkbox__label" for="solid-fuel-example-mutually-exclusive-checkbox"
id="solid-fuel-example-mutually-exclusive-checkbox-label">Solid fuel</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="other-fuel-example-mutually-exclusive-checkbox"
class="ons-checkbox__input ons-js-checkbox ons-js-exclusive-group-item ons-js-other" value="other"
aria-controls="other-fuel-example-mutually-exclusive-checkbox-other-wrap" aria-haspopup="true" />
<label class=" ons-checkbox__label" for="other-fuel-example-mutually-exclusive-checkbox"
id="other-fuel-example-mutually-exclusive-checkbox-label">Other</label>
<span class="ons-checkbox__other" id="other-fuel-example-mutually-exclusive-checkbox-other-wrap">
<label class="ons-label ons-u-fw-n" for="other-fuel-textbox-example-mutually-exclusive-checkbox"
id="other-fuel-textbox-example-mutually-exclusive-checkbox-label">Please specify</label>
<input type="text" id="other-fuel-textbox-example-mutually-exclusive-checkbox"
class="ons-input ons-input--text ons-input-type__input ons-js-exclusive-group-item ons-input--w-auto"
name="other-fuel-answer" />
</span>
</span>
</span>
</div>
<p class="ons-checkboxes--mutually-exclusive__item ons-u-mt-s">
<span class="ons-checkboxes__label ons-u-fs-r--b" aria-hidden="true">Or</span>
<span class="ons-checkbox">
<input type="checkbox" id="no-central-heating-example-mutually-exclusive-checkbox"
class="ons-checkbox__input ons-js-checkbox ons-js-exclusive-option" value="no-central-heating"
data-attribute="Example attribute"
data-deselect-message="Selecting this will uncheck all other checkboxes" />
<label class=" ons-checkbox__label" for="no-central-heating-example-mutually-exclusive-checkbox"
id="no-central-heating-example-mutually-exclusive-checkbox-label"><span class="ons-u-vh">Or, </span> No
central heating</label>
</span>
</p>
<span class="ons-js-exclusive-alert ons-u-vh" role="alert" aria-live="polite"
data-group-adjective="deselected" data-option-adjective="deselected"></span>
</div>
</div>
</fieldset>
</div>
</div>Mutually exclusive checkbox with multiple options
Use this variant if there is more than one contrasting answer that the user will need to select from.
Example Mutually Exclusive Multiple Options contents
Nunjucks
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{% from "components/question/_macro.njk" import onsQuestion %}
{%
call onsQuestion({
"title": "What type of central heating do you have?",
"legendIsQuestionTitle": true
})
%}
{{
onsCheckboxes({
"id": "central-heating-answers",
"dontWrap": true,
"checkboxesLabel": "Select all that apply",
"name": "mutually-exclusive",
"checkboxes": [
{
"id": "gas-example-mutually-exclusive-multiple-options",
"label": {
"text": "Gas"
},
"value": "gas"
},
{
"id": "electric-example-mutually-exclusive-multiple-options",
"label": {
"text": "Electric"
},
"value": "electric"
},
{
"id": "solid-fuel-example-mutually-exclusive-multiple-options",
"label": {
"text": "Solid fuel"
},
"value": "solid-fuel"
}
],
"mutuallyExclusive": {
"or": "Or",
"deselectMessage": "Selecting these will uncheck all other checkboxes",
"deselectGroupAdjective": "deselected",
"deselectExclusiveOptionAdjective": "deselected",
"exclusiveOptions": [
{
"id": "no-central-heating-example-mutually-exclusive-multiple-options",
"name": "no central heating",
"label": {
"text": "No central heating"
},
"value": "no-central-heating"
},
{
"id": "other-example-mutually-exclusive-multiple-options",
"name": "other",
"label": {
"text": "Other"
},
"value": "other"
}
]
}
})
}}
{% endcall %}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to apply to the fieldset |
| legend | string | true (unless legendIsQuestionTitle is set) | Text for the fieldset’s legend |
| legendClasses | string | false | Classes to apply to the legend element |
| legendIsQuestionTitle | boolean | true (unless legend is set) | Creates an h1 inside the legend. Use when there is only a single fieldset on the page |
| description | string | false | Description for the fieldset |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| exclusiveOptions | Array<Checkbox> or Array<radio> | true | Configuration for the mutually exclusive options |
| or | string | false | Text for the “Or” label that separates the mutually exclusive checkbox from the answer options, defaults to "Or". |
| deselectMessage | string | true | The text the aria-live alert will announce to warn that selecting the exclusive checkbox will clear or unselect all other answer options. For example, ”Selecting this will uncheck all other checkboxes”. |
| deselectGroupAdjective | string | true | The text the aria-live alert will announce when an answer option is cleared or unselected when the mutually exclusive checkbox is selected |
| deselectExclusiveOptionAdjective | string | true | The text the aria-live alert will announce when an option is cleared or unselected when the mutually exclusive checkbox is selected |
| error | Error (ref) | false | Configuration for validation errors |
| dontWrap | boolean | false | Prevents fields,checkboxes,date input,duration,input and Textarea from being wrapped in a fieldset component |
| autosuggestresults | string | false | Shows suggested options to users as they enter something into an input field |
HTML
<div class="ons-question ons-u-mb-xl">
<div class="ons-question__answer ons-u-mb-l">
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend ons-u-mb-no">
<h1 id="fieldset-legend-title" class="ons-fieldset__legend-title">What type of central heating do you have?</h1>
</legend>
<div class="ons-input-items">
<div class="ons-js-mutually-exclusive ons-mutually-exclusive">
<p class="ons-checkboxes__label"> Select all that apply </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="gas-example-mutually-exclusive-multiple-options"
class="ons-checkbox__input ons-js-checkbox ons-js-exclusive-group-item" value="gas" />
<label class=" ons-checkbox__label" for="gas-example-mutually-exclusive-multiple-options"
id="gas-example-mutually-exclusive-multiple-options-label">Gas</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="electric-example-mutually-exclusive-multiple-options"
class="ons-checkbox__input ons-js-checkbox ons-js-exclusive-group-item" value="electric" />
<label class=" ons-checkbox__label" for="electric-example-mutually-exclusive-multiple-options"
id="electric-example-mutually-exclusive-multiple-options-label">Electric</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="solid-fuel-example-mutually-exclusive-multiple-options"
class="ons-checkbox__input ons-js-checkbox ons-js-exclusive-group-item" value="solid-fuel" />
<label class=" ons-checkbox__label" for="solid-fuel-example-mutually-exclusive-multiple-options"
id="solid-fuel-example-mutually-exclusive-multiple-options-label">Solid fuel</label>
</span>
</span>
</div>
<p class="ons-checkboxes--mutually-exclusive__item ons-u-mt-s">
<span class="ons-checkboxes__label ons-u-fs-r--b" aria-hidden="true">Or</span>
<div class="ons-input-items">
<div class="ons-radios__items">
<span class="ons-radios__item">
<span class="ons-radio">
<input type="radio" id="no-central-heating-example-mutually-exclusive-multiple-options"
class="ons-radio__input ons-js-radio ons-js-exclusive-option" value="no-central-heating"
name="no central heating" />
<label class=" ons-radio__label" for="no-central-heating-example-mutually-exclusive-multiple-options"
id="no-central-heating-example-mutually-exclusive-multiple-options-label">No central heating</label>
</span>
</span>
<br />
<span class="ons-radios__item">
<span class="ons-radio">
<input type="radio" id="other-example-mutually-exclusive-multiple-options"
class="ons-radio__input ons-js-radio ons-js-exclusive-option" value="other"
name="no central heating" />
<label class=" ons-radio__label" for="other-example-mutually-exclusive-multiple-options"
id="other-example-mutually-exclusive-multiple-options-label">Other</label>
</span>
</span>
</div>
</div>
</p>
<span class="ons-js-exclusive-alert ons-u-vh" role="alert" aria-live="polite"
data-group-adjective="deselected" data-option-adjective="deselected"></span>
</div>
</div>
</fieldset>
</div>
</div>Checkbox with revealed text input
This variant lets the user provide an answer other to the options in the list, or to provide additional information required to describe their answer.
Set the other object with the required input parameters. The field is hidden until the checkbox is selected.
Example Checkboxes With Revealed Text Input contents
Nunjucks
{% from "components/question/_macro.njk" import onsQuestion %}
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{%
call onsQuestion({
"title": "Do you have any dietary requirements?",
"legendIsQuestionTitle": true,
"classes": "ons-u-mt-no"
})
%}
{{
onsCheckboxes({
"checkboxesLabel": "Select all that apply",
"dontWrap": true,
"checkboxes": [
{
"id": "gluten-free-example-checkbox-with-revealed-text-input",
"label": {
"text": "Gluten free"
},
"value": "gluten-free"
},
{
"id": "lactose-intolerant-example-checkbox-with-revealed-text-input",
"label": {
"text": "Lactose intolerant"
},
"value": "lactose-intolerant"
},
{
"id": "vegan-example-checkbox-with-revealed-text-input",
"label": {
"text": "Vegan"
},
"value": "vegan"
},
{
"id": "vegetarian-example-checkbox-with-revealed-text-input",
"label": {
"text": "Vegetarian"
},
"value": "vegetarian"
},
{
"id": "other-checkbox-with-revealed-text-input",
"label": {
"text": "Other"
},
"value": "other",
"other": {
"id": "other-textbox-example-checkbox-with-revealed-text-input",
"name": "other-answer",
"label": {
"text": "Enter dietary requirements"
}
}
}
]
})
}}
{% endcall %}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<div class="ons-question ons-u-mb-xl ons-u-mt-no">
<div class="ons-question__answer ons-u-mb-l">
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend ons-u-mb-no">
<h1 id="fieldset-legend-title" class="ons-fieldset__legend-title">Do you have any dietary requirements?</h1>
</legend>
<div class="ons-input-items">
<p class="ons-checkboxes__label"> Select all that apply </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="gluten-free-example-checkbox-with-revealed-text-input"
class="ons-checkbox__input ons-js-checkbox" value="gluten-free" />
<label class=" ons-checkbox__label" for="gluten-free-example-checkbox-with-revealed-text-input"
id="gluten-free-example-checkbox-with-revealed-text-input-label">Gluten free</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="lactose-intolerant-example-checkbox-with-revealed-text-input"
class="ons-checkbox__input ons-js-checkbox" value="lactose-intolerant" />
<label class=" ons-checkbox__label" for="lactose-intolerant-example-checkbox-with-revealed-text-input"
id="lactose-intolerant-example-checkbox-with-revealed-text-input-label">Lactose intolerant</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="vegan-example-checkbox-with-revealed-text-input"
class="ons-checkbox__input ons-js-checkbox" value="vegan" />
<label class=" ons-checkbox__label" for="vegan-example-checkbox-with-revealed-text-input"
id="vegan-example-checkbox-with-revealed-text-input-label">Vegan</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="vegetarian-example-checkbox-with-revealed-text-input"
class="ons-checkbox__input ons-js-checkbox" value="vegetarian" />
<label class=" ons-checkbox__label" for="vegetarian-example-checkbox-with-revealed-text-input"
id="vegetarian-example-checkbox-with-revealed-text-input-label">Vegetarian</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="other-checkbox-with-revealed-text-input"
class="ons-checkbox__input ons-js-checkbox ons-js-other" value="other"
aria-controls="other-checkbox-with-revealed-text-input-other-wrap" aria-haspopup="true" />
<label class=" ons-checkbox__label" for="other-checkbox-with-revealed-text-input"
id="other-checkbox-with-revealed-text-input-label">Other</label>
<span class="ons-checkbox__other" id="other-checkbox-with-revealed-text-input-other-wrap">
<label class="ons-label ons-u-fw-n" for="other-textbox-example-checkbox-with-revealed-text-input"
id="other-textbox-example-checkbox-with-revealed-text-input-label">Enter dietary requirements</label>
<input type="text" id="other-textbox-example-checkbox-with-revealed-text-input"
class="ons-input ons-input--text ons-input-type__input ons-input--w-auto" name="other-answer" />
</span>
</span>
</span>
</div>
</div>
</fieldset>
</div>
</div>Checkbox with revealed select
This variant reveals a nested select component when a checkbox is selected.
To use this variant set "otherType": "select" inside the other object.
Example Checkboxes With Revealed Select contents
Nunjucks
{% from "components/question/_macro.njk" import onsQuestion %}
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{%
call onsQuestion({
"title": "How would you like us to contact you?",
"legendIsQuestionTitle": true,
"classes": "ons-u-mt-no"
})
%}
{{
onsCheckboxes({
"checkboxesLabel": "Select all that apply",
"dontWrap": true,
"name": "contact",
"checkboxes": [
{
"id": "post-example-checkbox-with-revealed-select",
"label": {
"text": "By post"
},
"value": "post"
},
{
"id": "email-example-checkbox-with-revealed-select",
"label": {
"text": "By email"
},
"value": "email"
},
{
"id": "phone-example-checkbox-with-revealed-select",
"label": {
"text": "By phone"
},
"value": "phone",
"other": {
"otherType": "select",
"id": "phone-time-example-checkbox-with-revealed-select",
"name": "phone-time",
"label": {
"text": "Choose preferred time of day"
},
"options": [
{
"value": "",
"text": "Select an option",
"disabled": true,
"selected": true
},
{
"value": "anytime",
"text": "Anytime of day"
},
{
"value": "morning",
"text": "Morning"
},
{
"value": "afternoon",
"text": "Afternoon"
},
{
"value": "evening",
"text": "Evening"
}
]
}
}
]
})
}}
{% endcall %}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<div class="ons-question ons-u-mb-xl ons-u-mt-no">
<div class="ons-question__answer ons-u-mb-l">
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend ons-u-mb-no">
<h1 id="fieldset-legend-title" class="ons-fieldset__legend-title">How would you like us to contact you?</h1>
</legend>
<div class="ons-input-items">
<p class="ons-checkboxes__label"> Select all that apply </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="post-example-checkbox-with-revealed-select"
class="ons-checkbox__input ons-js-checkbox" value="post" />
<label class=" ons-checkbox__label" for="post-example-checkbox-with-revealed-select"
id="post-example-checkbox-with-revealed-select-label">By post</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="email-example-checkbox-with-revealed-select"
class="ons-checkbox__input ons-js-checkbox" value="email" />
<label class=" ons-checkbox__label" for="email-example-checkbox-with-revealed-select"
id="email-example-checkbox-with-revealed-select-label">By email</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="phone-example-checkbox-with-revealed-select"
class="ons-checkbox__input ons-js-checkbox ons-js-other" value="phone"
aria-controls="phone-example-checkbox-with-revealed-select-other-wrap" aria-haspopup="true" />
<label class=" ons-checkbox__label" for="phone-example-checkbox-with-revealed-select"
id="phone-example-checkbox-with-revealed-select-label">By phone</label>
<span class="ons-checkbox__other" id="phone-example-checkbox-with-revealed-select-other-wrap">
<label class="ons-label ons-u-fw-n" for="phone-time-example-checkbox-with-revealed-select">Choose
preferred time of day</label>
<select id="phone-time-example-checkbox-with-revealed-select" name="phone-time"
class="ons-input ons-input--select">
<option value="" selected disabled>Select an option</option>
<option value="anytime">Anytime of day</option>
<option value="morning">Morning</option>
<option value="afternoon">Afternoon</option>
<option value="evening">Evening</option>
</select>
</span>
</span>
</span>
</div>
</div>
</fieldset>
</div>
</div>Checkbox with visible text input
This variant always shows the nested inputs.
To use this variant set "open": true inside the other object.
Example Checkboxes With Visible Text Input contents
Nunjucks
{% from "components/question/_macro.njk" import onsQuestion %}
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{%
call onsQuestion({
"title": "Do you have any dietary requirements?",
"legendIsQuestionTitle": true,
"classes": "ons-u-mt-no"
})
%}
{{
onsCheckboxes({
"checkboxesLabel": "Select all that apply",
"dontWrap": true,
"name": "dietary",
"checkboxes": [
{
"id": "gluten-free-example-checkbox-with-visible-text-input",
"label": {
"text": "Gluten free"
},
"value": "gluten-free"
},
{
"id": "lactose-intolerant-example-checkbox-with-visible-text-input",
"label": {
"text": "Lactose intolerant"
},
"value": "lactose-intolerant"
},
{
"id": "vegan-example-checkbox-with-visible-text-input",
"label": {
"text": "Vegan"
},
"value": "vegan"
},
{
"id": "vegetarian-example-checkbox-with-visible-text-input",
"label": {
"text": "Vegetarian"
},
"value": "vegetarian"
},
{
"id": "other-checkbox-with-visible-text-input",
"label": {
"text": "Other"
},
"value": "other",
"other": {
"open": true,
"id": "other-textbox-example-checkbox-with-visible-text-input",
"name": "other-answer",
"label": {
"text": "Enter dietary requirements"
}
}
}
]
})
}}
{% endcall %}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<div class="ons-question ons-u-mb-xl ons-u-mt-no">
<div class="ons-question__answer ons-u-mb-l">
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend ons-u-mb-no">
<h1 id="fieldset-legend-title" class="ons-fieldset__legend-title">Do you have any dietary requirements?</h1>
</legend>
<div class="ons-input-items">
<p class="ons-checkboxes__label"> Select all that apply </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="gluten-free-example-checkbox-with-visible-text-input"
class="ons-checkbox__input ons-js-checkbox" value="gluten-free" />
<label class=" ons-checkbox__label" for="gluten-free-example-checkbox-with-visible-text-input"
id="gluten-free-example-checkbox-with-visible-text-input-label">Gluten free</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="lactose-intolerant-example-checkbox-with-visible-text-input"
class="ons-checkbox__input ons-js-checkbox" value="lactose-intolerant" />
<label class=" ons-checkbox__label" for="lactose-intolerant-example-checkbox-with-visible-text-input"
id="lactose-intolerant-example-checkbox-with-visible-text-input-label">Lactose intolerant</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="vegan-example-checkbox-with-visible-text-input"
class="ons-checkbox__input ons-js-checkbox" value="vegan" />
<label class=" ons-checkbox__label" for="vegan-example-checkbox-with-visible-text-input"
id="vegan-example-checkbox-with-visible-text-input-label">Vegan</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="vegetarian-example-checkbox-with-visible-text-input"
class="ons-checkbox__input ons-js-checkbox" value="vegetarian" />
<label class=" ons-checkbox__label" for="vegetarian-example-checkbox-with-visible-text-input"
id="vegetarian-example-checkbox-with-visible-text-input-label">Vegetarian</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="other-checkbox-with-visible-text-input"
class="ons-checkbox__input ons-js-checkbox ons-js-other" value="other" />
<label class=" ons-checkbox__label" for="other-checkbox-with-visible-text-input"
id="other-checkbox-with-visible-text-input-label">Other</label>
<span class="ons-checkbox__other ons-checkbox__other--open"
id="other-checkbox-with-visible-text-input-other-wrap">
<label class="ons-label ons-u-fw-n" for="other-textbox-example-checkbox-with-visible-text-input"
id="other-textbox-example-checkbox-with-visible-text-input-label">Enter dietary requirements</label>
<input type="text" id="other-textbox-example-checkbox-with-visible-text-input"
class="ons-input ons-input--text ons-input-type__input ons-input--w-auto" name="other-answer" />
</span>
</span>
</span>
</div>
</div>
</fieldset>
</div>
</div>Checkboxes without a border
This variant removes the border around the checkbox and label.
Do not use this variant on question pages with checkboxes. It is better to have a border. It makes the checkboxes more visible for users and gives them a larger target area to select (the label and the boundary).
Only remove the checkbox border for pages that are not following the practice of “one thing per page”, where the checkboxes are not the primary call to action.
Example Checkboxes Without Border contents
Nunjucks
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{{
onsCheckboxes({
"checkboxesLabel": "All types",
"legend": "Select type",
"name": "types",
"borderless": true,
"checkboxes": [
{
"id": "booklet-example-checkbox-without-border",
"label": {
"text": "Booklet"
},
"value": "booklet"
},
{
"id": "logo-example-checkbox-without-border",
"label": {
"text": "Logo"
},
"value": "logo"
},
{
"id": "poster-example-checkbox-without-border",
"label": {
"text": "Poster"
},
"value": "poster"
}
]
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend"><span class="ons-fieldset__legend-title ons-u-pb-no">Select type</span></legend>
<p class="ons-checkboxes__label"> All types </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="booklet-example-checkbox-without-border" class="ons-checkbox__input ons-js-checkbox"
value="booklet" />
<label class=" ons-checkbox__label" for="booklet-example-checkbox-without-border"
id="booklet-example-checkbox-without-border-label">Booklet</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="logo-example-checkbox-without-border" class="ons-checkbox__input ons-js-checkbox"
value="logo" />
<label class=" ons-checkbox__label" for="logo-example-checkbox-without-border"
id="logo-example-checkbox-without-border-label">Logo</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="poster-example-checkbox-without-border" class="ons-checkbox__input ons-js-checkbox"
value="poster" />
<label class=" ons-checkbox__label" for="poster-example-checkbox-without-border"
id="poster-example-checkbox-without-border-label">Poster</label>
</span>
</span>
</div>
</fieldset>Checkbox with hidden label
This variant visually hides the label of a single checkbox with the parameter hideLabel: true.
This may be appropriate in certain circumstances. For example, when onsCheckbox is implemented inside a table cell. A label is not visually required as the table header and table row provide sufficient context of what the checkbox' purpose is. The label configuration is still required but will be visually hidden and will still allow screen readers to understand the purpose.
In the example below the hidden label text is a combination of the th for the checkbox and the related td for the tr e.g. 'Edit Surveys'
Example Checkboxes With Hidden Label contents
Nunjucks
{% from "components/checkboxes/_checkbox-macro.njk" import onsCheckbox %}
<div class="ons-grid ons-grid-flex ons-grid-flex--between">
<div class="ons-grid__col">
<h1 class="ons-u-fs-l u-mb-2xs" name="page-manage-account-title">{{ name }}</h1>
</div>
</div>
<div class="ons-grid ons-grid-flex ons-grid-flex--between">
<div class="ons-grid__col">
<h2 class="ons-u-fs-m u-mb-2xs" name="page-manage-account-subtitle">Select user permissions</h2>
</div>
</div>
<form id="user-permissions" action="" method="post">
<input type="hidden" name="csrf_token" value="" />
<section class="ons-u-mt-s">
<table id="tbl-users" class="ons-table">
<thead class="ons-table__head">
<tr class="ons-table__row">
<th scope="col" class="ons-table__header">
<span>Survey Data Collection area</span>
</th>
<th scope="col" class="ons-table__header">
<span>View</span>
</th>
<th scope="col" class="ons-table__header">
<span>Edit</span>
</th>
<th scope="col" class="ons-table__header">
<span>Delete</span>
</th>
</tr>
</thead>
<tbody class="ons-table__body">
<tr class="ons-table__row">
<td class="ons-table__cell">Surveys</td>
<td class="ons-table__cell">
{{
onsCheckbox({
"id": "surveys-view-example-checkbox-with-hidden-label",
"hideLabel": true,
"label": {
"text": "View surveys"
},
"value": "y",
"checked": true,
"disabled": true
})
}}
</td>
<td class="ons-table__cell" colspan="2">
{{
onsCheckbox({
"id": "surveys-edit-example-checkbox-with-hidden-label",
"hideLabel": true,
"label": {
"text": "Edit surveys"
},
"value": "n"
})
}}
</td>
</tr>
<tr class="ons-table__row">
<td class="ons-table__cell">Reporting units</td>
<td class="ons-table__cell">
{{
onsCheckbox({
"id": "reporting-units-view-example-checkbox-with-hidden-label",
"hideLabel": true,
"label": {
"text": "View reporting units"
},
"value": "y",
"checked": true,
"disabled": true
})
}}
</td>
<td class="ons-table__cell" colspan="2">
{{
onsCheckbox({
"id": "reporting-units-edit-example-checkbox-with-hidden-label",
"hideLabel": true,
"label": {
"text": "Edit reporting units"
},
"value": "n"
})
}}
</td>
</tr>
<tr class="ons-table__row">
<td class="ons-table__cell">Respondents</td>
<td class="ons-table__cell">
{{
onsCheckbox({
"id": "respondents-view-example-checkbox-with-hidden-label",
"hideLabel": true,
"label": {
"text": "View respondents"
},
"value": "y",
"checked": true,
"disabled": true
})
}}
</td>
<td class="ons-table__cell">
{{
onsCheckbox({
"id": "respondents-edit-example-checkbox-with-hidden-label",
"hideLabel": true,
"label": {
"text": "Edit respondents"
},
"value": "y",
"checked": true
})
}}
</td>
<td class="ons-table__cell">
{{
onsCheckbox({
"id": "respondents-delete-example-checkbox-with-hidden-label",
"hideLabel": true,
"label": {
"text": "Delete respondents"
},
"value": "n"
})
}}
</td>
</tr>
<tr class="ons-table__row">
<td class="ons-table__cell">Messages</td>
<td class="ons-table__cell">
{{
onsCheckbox({
"id": "messages-view-example-checkbox-with-hidden-label",
"hideLabel": true,
"label": {
"text": "View messages"
},
"value": "y",
"checked": true,
"disabled": true
})
}}
</td>
<td class="ons-table__cell" colspan="2">
{{
onsCheckbox({
"id": "messages-edit-example-checkbox-with-hidden-label",
"hideLabel": true,
"label": {
"text": "Edit messages"
},
"value": "y",
"checked": true
})
}}
</td>
</tr>
</tbody>
</table>
</section>
</form>
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<div class="ons-grid ons-grid-flex ons-grid-flex--between">
<div class="ons-grid__col">
<h1 class="ons-u-fs-l u-mb-2xs" name="page-manage-account-title"></h1>
</div>
</div>
<div class="ons-grid ons-grid-flex ons-grid-flex--between">
<div class="ons-grid__col">
<h2 class="ons-u-fs-m u-mb-2xs" name="page-manage-account-subtitle">Select user permissions</h2>
</div>
</div>
<form id="user-permissions" action="" method="post">
<input type="hidden" name="csrf_token" value="" />
<section class="ons-u-mt-s">
<table id="tbl-users" class="ons-table">
<thead class="ons-table__head">
<tr class="ons-table__row">
<th scope="col" class="ons-table__header">
<span>Survey Data Collection area</span>
</th>
<th scope="col" class="ons-table__header">
<span>View</span>
</th>
<th scope="col" class="ons-table__header">
<span>Edit</span>
</th>
<th scope="col" class="ons-table__header">
<span>Delete</span>
</th>
</tr>
</thead>
<tbody class="ons-table__body">
<tr class="ons-table__row">
<td class="ons-table__cell">Surveys</td>
<td class="ons-table__cell">
<span class="ons-checkbox ons-checkbox--no-label">
<input type="checkbox" id="surveys-view-example-checkbox-with-hidden-label"
class="ons-checkbox__input ons-js-checkbox" value="y" disabled aria-disabled="true" checked />
<label class=" ons-checkbox__label" for="surveys-view-example-checkbox-with-hidden-label"
id="surveys-view-example-checkbox-with-hidden-label-label">View surveys</label>
</span>
</td>
<td class="ons-table__cell" colspan="2">
<span class="ons-checkbox ons-checkbox--no-label">
<input type="checkbox" id="surveys-edit-example-checkbox-with-hidden-label"
class="ons-checkbox__input ons-js-checkbox" value="n" />
<label class=" ons-checkbox__label" for="surveys-edit-example-checkbox-with-hidden-label"
id="surveys-edit-example-checkbox-with-hidden-label-label">Edit surveys</label>
</span>
</td>
</tr>
<tr class="ons-table__row">
<td class="ons-table__cell">Reporting units</td>
<td class="ons-table__cell">
<span class="ons-checkbox ons-checkbox--no-label">
<input type="checkbox" id="reporting-units-view-example-checkbox-with-hidden-label"
class="ons-checkbox__input ons-js-checkbox" value="y" disabled aria-disabled="true" checked />
<label class=" ons-checkbox__label" for="reporting-units-view-example-checkbox-with-hidden-label"
id="reporting-units-view-example-checkbox-with-hidden-label-label">View reporting units</label>
</span>
</td>
<td class="ons-table__cell" colspan="2">
<span class="ons-checkbox ons-checkbox--no-label">
<input type="checkbox" id="reporting-units-edit-example-checkbox-with-hidden-label"
class="ons-checkbox__input ons-js-checkbox" value="n" />
<label class=" ons-checkbox__label" for="reporting-units-edit-example-checkbox-with-hidden-label"
id="reporting-units-edit-example-checkbox-with-hidden-label-label">Edit reporting units</label>
</span>
</td>
</tr>
<tr class="ons-table__row">
<td class="ons-table__cell">Respondents</td>
<td class="ons-table__cell">
<span class="ons-checkbox ons-checkbox--no-label">
<input type="checkbox" id="respondents-view-example-checkbox-with-hidden-label"
class="ons-checkbox__input ons-js-checkbox" value="y" disabled aria-disabled="true" checked />
<label class=" ons-checkbox__label" for="respondents-view-example-checkbox-with-hidden-label"
id="respondents-view-example-checkbox-with-hidden-label-label">View respondents</label>
</span>
</td>
<td class="ons-table__cell">
<span class="ons-checkbox ons-checkbox--no-label">
<input type="checkbox" id="respondents-edit-example-checkbox-with-hidden-label"
class="ons-checkbox__input ons-js-checkbox" value="y" checked />
<label class=" ons-checkbox__label" for="respondents-edit-example-checkbox-with-hidden-label"
id="respondents-edit-example-checkbox-with-hidden-label-label">Edit respondents</label>
</span>
</td>
<td class="ons-table__cell">
<span class="ons-checkbox ons-checkbox--no-label">
<input type="checkbox" id="respondents-delete-example-checkbox-with-hidden-label"
class="ons-checkbox__input ons-js-checkbox" value="n" />
<label class=" ons-checkbox__label" for="respondents-delete-example-checkbox-with-hidden-label"
id="respondents-delete-example-checkbox-with-hidden-label-label">Delete respondents</label>
</span>
</td>
</tr>
<tr class="ons-table__row">
<td class="ons-table__cell">Messages</td>
<td class="ons-table__cell">
<span class="ons-checkbox ons-checkbox--no-label">
<input type="checkbox" id="messages-view-example-checkbox-with-hidden-label"
class="ons-checkbox__input ons-js-checkbox" value="y" disabled aria-disabled="true" checked />
<label class=" ons-checkbox__label" for="messages-view-example-checkbox-with-hidden-label"
id="messages-view-example-checkbox-with-hidden-label-label">View messages</label>
</span>
</td>
<td class="ons-table__cell" colspan="2">
<span class="ons-checkbox ons-checkbox--no-label">
<input type="checkbox" id="messages-edit-example-checkbox-with-hidden-label"
class="ons-checkbox__input ons-js-checkbox" value="y" checked />
<label class=" ons-checkbox__label" for="messages-edit-example-checkbox-with-hidden-label"
id="messages-edit-example-checkbox-with-hidden-label-label">Edit messages</label>
</span>
</td>
</tr>
</tbody>
</table>
</section>
</form>Checkbox with revealed checkboxes
This variant reveals nested checkboxes when a checkbox is selected. We recommend using this variant with the borderless variant.
To use this variant set "otherType": "checkboxes" inside the other object. The example below includes the optional parameter selectAllChildren: true which automatically checks all revealed checkboxes.
Example Checkboxes With Revealed Checkboxes contents
Nunjucks
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{{
onsCheckboxes({
"legend": "Content type",
"checkboxesLabel": "Show only:",
"borderless": true,
"name": "dietary",
"checkboxes": [
{
"id": "data-example-with-revealed-checkboxes",
"label": {
"text": "Data (309)"
},
"value": "data",
"other": {
"otherType": "checkboxes",
"selectAllChildren": true,
"legend": "Data type",
"legendClasses": "ons-u-vh",
"name": "name",
"checkboxes": [
{
"id": "datasets-example-with-revealed-checkboxes",
"label": {
"text": "Datasets (100)"
},
"value": "datasets"
},
{
"id": "timeseries-example-with-revealed-checkboxes",
"label": {
"text": "Timeseries (20)"
},
"value": "timeseries"
},
{
"id": "requested-example-with-revealed-checkboxes",
"label": {
"text": "User requested data (17)"
},
"value": "requested"
}
]
}
},
{
"id": "publications-example-with-revealed-checkboxes",
"label": {
"text": "Publications (137)"
},
"value": "publications",
"other": {
"otherType": "checkboxes",
"selectAllChildren": true,
"legend": "Publication type",
"legendClasses": "ons-u-vh",
"name": "name",
"checkboxes": [
{
"id": "press-release-example-with-revealed-checkboxes",
"label": {
"text": "Press release (100)"
},
"value": "pressrelease"
},
{
"id": "bulletin-example-with-revealed-checkboxes",
"label": {
"text": "Bulletin (20)"
},
"value": "bulletin"
}
]
}
},
{
"id": "areas-example-with-revealed-checkboxes",
"label": {
"text": "Areas (0)"
},
"value": "areas"
}
]
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend"><span class="ons-fieldset__legend-title ons-u-pb-no">Content type</span></legend>
<p class="ons-checkboxes__label"> Show only: </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="data-example-with-revealed-checkboxes"
class="ons-checkbox__input ons-js-checkbox ons-js-other ons-js-select-all-children" value="data"
aria-controls="data-example-with-revealed-checkboxes-other-wrap" aria-haspopup="true" />
<label class=" ons-checkbox__label" for="data-example-with-revealed-checkboxes"
id="data-example-with-revealed-checkboxes-label">Data (309)</label>
<span class="ons-checkbox__other" id="data-example-with-revealed-checkboxes-other-wrap">
<fieldset class="ons-fieldset ons-js-other-fieldset-checkbox">
<legend class="ons-fieldset__legend ons-u-vh"><span class="ons-fieldset__legend-title ons-u-pb-no">Data
type</span></legend>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="datasets-example-with-revealed-checkboxes"
class="ons-checkbox__input ons-js-checkbox" value="datasets" />
<label class=" ons-checkbox__label" for="datasets-example-with-revealed-checkboxes"
id="datasets-example-with-revealed-checkboxes-label">Datasets (100)</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="timeseries-example-with-revealed-checkboxes"
class="ons-checkbox__input ons-js-checkbox" value="timeseries" />
<label class=" ons-checkbox__label" for="timeseries-example-with-revealed-checkboxes"
id="timeseries-example-with-revealed-checkboxes-label">Timeseries (20)</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="requested-example-with-revealed-checkboxes"
class="ons-checkbox__input ons-js-checkbox" value="requested" />
<label class=" ons-checkbox__label" for="requested-example-with-revealed-checkboxes"
id="requested-example-with-revealed-checkboxes-label">User requested data (17)</label>
</span>
</span>
</div>
</fieldset>
</span>
</span>
</span>
<br />
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="publications-example-with-revealed-checkboxes"
class="ons-checkbox__input ons-js-checkbox ons-js-other ons-js-select-all-children" value="publications"
aria-controls="publications-example-with-revealed-checkboxes-other-wrap" aria-haspopup="true" />
<label class=" ons-checkbox__label" for="publications-example-with-revealed-checkboxes"
id="publications-example-with-revealed-checkboxes-label">Publications (137)</label>
<span class="ons-checkbox__other" id="publications-example-with-revealed-checkboxes-other-wrap">
<fieldset class="ons-fieldset ons-js-other-fieldset-checkbox">
<legend class="ons-fieldset__legend ons-u-vh"><span
class="ons-fieldset__legend-title ons-u-pb-no">Publication type</span></legend>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="press-release-example-with-revealed-checkboxes"
class="ons-checkbox__input ons-js-checkbox" value="pressrelease" />
<label class=" ons-checkbox__label" for="press-release-example-with-revealed-checkboxes"
id="press-release-example-with-revealed-checkboxes-label">Press release (100)</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="bulletin-example-with-revealed-checkboxes"
class="ons-checkbox__input ons-js-checkbox" value="bulletin" />
<label class=" ons-checkbox__label" for="bulletin-example-with-revealed-checkboxes"
id="bulletin-example-with-revealed-checkboxes-label">Bulletin (20)</label>
</span>
</span>
</div>
</fieldset>
</span>
</span>
</span>
<br />
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="areas-example-with-revealed-checkboxes"
class="ons-checkbox__input ons-js-checkbox ons-js-other ons-js-select-all-children" value="areas" />
<label class=" ons-checkbox__label" for="areas-example-with-revealed-checkboxes"
id="areas-example-with-revealed-checkboxes-label">Areas (0)</label>
</span>
</span>
</div>
</fieldset>Checkbox with revealed radios
This variant reveals nested radios when a checkbox is selected. We recommend using this variant together with the parent checkboxes using the borderless variant.
To use this variant set "otherType": "radios" inside the other object.
Example Checkboxes With Revealed Radios contents
Nunjucks
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{{
onsCheckboxes({
"checkboxesLabel": "Select all that apply",
"legend": "How would you like us to contact you?",
"name": "contact",
"borderless": true,
"checkboxes": [
{
"id": "post-example-with-revealed-radios",
"label": {
"text": "By post"
},
"value": "post"
},
{
"id": "email-example-with-revealed-radios",
"label": {
"text": "By email"
},
"value": "email"
},
{
"id": "phone-example-with-revealed-radios",
"label": {
"text": "By phone"
},
"value": "phone",
"other": {
"otherType": "radios",
"id": "phone-time-example-with-revealed-radios",
"name": "phone-time",
"legend": "Choose preferred time of day",
"radios": [
{
"value": "anytime",
"id": "anytime-example-with-revealed-radios",
"label": {
"text": "Any time of day"
}
},
{
"value": "morning",
"id": "morning-example-with-revealed-radios",
"label": {
"text": "Morning"
}
},
{
"value": "afternoon",
"id": "afternoon-example-with-revealed-radios",
"label": {
"text": "Afternoon"
}
},
{
"value": "evening",
"id": "evening-example-with-revealed-radios",
"label": {
"text": "Evening"
}
}
]
}
}
]
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend"><span class="ons-fieldset__legend-title ons-u-pb-no">How would you like us to
contact you?</span></legend>
<p class="ons-checkboxes__label"> Select all that apply </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="post-example-with-revealed-radios" class="ons-checkbox__input ons-js-checkbox"
value="post" />
<label class=" ons-checkbox__label" for="post-example-with-revealed-radios"
id="post-example-with-revealed-radios-label">By post</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="email-example-with-revealed-radios" class="ons-checkbox__input ons-js-checkbox"
value="email" />
<label class=" ons-checkbox__label" for="email-example-with-revealed-radios"
id="email-example-with-revealed-radios-label">By email</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="phone-example-with-revealed-radios"
class="ons-checkbox__input ons-js-checkbox ons-js-other" value="phone"
aria-controls="phone-example-with-revealed-radios-other-wrap" aria-haspopup="true" />
<label class=" ons-checkbox__label" for="phone-example-with-revealed-radios"
id="phone-example-with-revealed-radios-label">By phone</label>
<span class="ons-checkbox__other" id="phone-example-with-revealed-radios-other-wrap">
<fieldset id="phone-time-example-with-revealed-radios" class="ons-fieldset ons-js-other-fieldset-checkbox">
<legend class="ons-fieldset__legend"><span class="ons-fieldset__legend-title ons-u-pb-no">Choose preferred
time of day</span></legend>
<div class="ons-radios__items">
<span class="ons-radios__item ons-radios__item--no-border">
<span class="ons-radio ons-radio--no-border">
<input type="radio" id="anytime-example-with-revealed-radios" class="ons-radio__input ons-js-radio"
value="anytime" name="phone-time" />
<label class=" ons-radio__label" for="anytime-example-with-revealed-radios"
id="anytime-example-with-revealed-radios-label">Any time of day</label>
</span>
</span>
<br />
<span class="ons-radios__item ons-radios__item--no-border">
<span class="ons-radio ons-radio--no-border">
<input type="radio" id="morning-example-with-revealed-radios" class="ons-radio__input ons-js-radio"
value="morning" name="phone-time" />
<label class=" ons-radio__label" for="morning-example-with-revealed-radios"
id="morning-example-with-revealed-radios-label">Morning</label>
</span>
</span>
<br />
<span class="ons-radios__item ons-radios__item--no-border">
<span class="ons-radio ons-radio--no-border">
<input type="radio" id="afternoon-example-with-revealed-radios" class="ons-radio__input ons-js-radio"
value="afternoon" name="phone-time" />
<label class=" ons-radio__label" for="afternoon-example-with-revealed-radios"
id="afternoon-example-with-revealed-radios-label">Afternoon</label>
</span>
</span>
<br />
<span class="ons-radios__item ons-radios__item--no-border">
<span class="ons-radio ons-radio--no-border">
<input type="radio" id="evening-example-with-revealed-radios" class="ons-radio__input ons-js-radio"
value="evening" name="phone-time" />
<label class=" ons-radio__label" for="evening-example-with-revealed-radios"
id="evening-example-with-revealed-radios-label">Evening</label>
</span>
</span>
</div>
</fieldset>
</span>
</span>
</span>
</div>
</fieldset>Disabled checkboxes
This variant enables the use of disabled checkboxes. Allowing for a consistent user interface even when some options aren't available.
Example Checkboxes Disabled contents
Nunjucks
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{{
onsCheckboxes({
"legend": "Content type",
"checkboxesLabel": "Show only:",
"borderless": true,
"name": "dietary",
"checkboxes": [
{
"id": "data-checkbox-disabled",
"label": {
"text": "Data (309)"
},
"value": "data"
},
{
"id": "publications-checkbox-disabled",
"label": {
"text": "Publications (137)"
},
"value": "publications"
},
{
"id": "areas-checkbox-disabled",
"label": {
"text": "Areas (0)"
},
"value": "areas",
"disabled": true
}
]
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend"><span class="ons-fieldset__legend-title ons-u-pb-no">Content type</span></legend>
<p class="ons-checkboxes__label"> Show only: </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="data-checkbox-disabled" class="ons-checkbox__input ons-js-checkbox" value="data" />
<label class=" ons-checkbox__label" for="data-checkbox-disabled" id="data-checkbox-disabled-label">Data
(309)</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="publications-checkbox-disabled" class="ons-checkbox__input ons-js-checkbox"
value="publications" />
<label class=" ons-checkbox__label" for="publications-checkbox-disabled"
id="publications-checkbox-disabled-label">Publications (137)</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item ons-checkboxes__item--no-border">
<span class="ons-checkbox ons-checkbox--no-border">
<input type="checkbox" id="areas-checkbox-disabled" class="ons-checkbox__input ons-js-checkbox" value="areas"
disabled aria-disabled="true" />
<label class=" ons-checkbox__label" for="areas-checkbox-disabled" id="areas-checkbox-disabled-label">Areas
(0)</label>
</span>
</span>
</div>
</fieldset>How to validate checkboxes
To help users make a selection on the page and provide extra detail if it is required, you should:
- check they have selected at least one checkbox
- check they have entered something or selected a drop-down option if more detail is required for one of the checkboxes
- show an error message if they have not selected any of the checkboxes or given any more detail when required
Error messages
Use the correct errors pattern and show the error details above the checkbox options.
Example Checkboxes Error contents
Nunjucks
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{{
onsCheckboxes({
"checkboxesLabel": "Select all that apply",
"name": "dietary",
"dontWrap": true,
"checkboxes": [
{
"id": "gluten-free-checkbox-error",
"label": {
"text": "Gluten free"
},
"value": "gluten-free"
},
{
"id": "lactose-intolerant-checkbox-error",
"label": {
"text": "Lactose intolerant"
},
"value": "lactose-intolerant"
},
{
"id": "vegan-checkbox-error",
"label": {
"text": "Vegan"
},
"value": "vegan"
},
{
"id": "vegetarian-checkbox-error",
"label": {
"text": "Vegetarian"
},
"value": "vegetarian"
},
{
"id": "other-checkbox-error",
"label": {
"text": "Other"
},
"checked": true,
"value": "other",
"other": {
"id": "other-textbox-checbox-error",
"name": "other-answer",
"label": {
"text": "Enter dietary requirements"
}
}
}
],
"error": {
"classes": "test",
"id": "dietary-error-checkbox",
"text": "Enter your dietary requirements"
}
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML legend for the fieldset |
| legendClasses | string | false | Classes to add to the fieldset‘s legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the fieldset |
| checkboxesLabel | string | true (unless inside a radio) | A prompt for the checkboxes, for example, “Select all that apply” |
| checkboxesLabelClasses | string | false | Classes to add to the checkboxes prompt element (checkboxesLabel) |
| checkboxes | array<Checkbox> | true | Settings for each checkbox |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| mutuallyExclusive | MutuallyExclusive (ref) | false | Configuration object to set if the checkboxes have a mutually exclusive opposing option |
| dontWrap | boolean | false | Prevents the checkboxes from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the checkboxes are the only fieldset on the page |
| autoSelect | object<AutoSelectButton> | false | Settings for the AutoSelect button |
| error | Error (ref) | false | Configuration for validation errors |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the checkbox. Used for the label’s for attribute. |
| name | string | false | The HTML name attribute for the checkbox |
| value | string | false | The HTML value attribute for the checkbox to set a preset value for the input |
| classes | string | false | Classes to add to the checkbox |
| inputClasses | string | false | Classes to apply to the checkbox input |
| checked | boolean | false | Set to “true” to check the checkbox when the page loads |
| disabled | boolean | false | Sets checkbox state to disabled and changes style of checkbox and label |
| label | Label (ref) | true | Settings for the checkbox label |
| hideLabel | boolean | false | Adds visually hidden class to the label if true |
| other | object<OtherCheckbox> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes or radios to provide other information in addition to the checkbox answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the checkbox input element |
| deselectMessage | string | false | For use with mutually exclusive checkboxes. The text the aria-live alert will read to warn that selecting the exclusive option will clear all other inputs. |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes” or “radios”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| selectAllText | string | true | Text label for button shown when at least one checkbox is unchecked, for example, “Select all” |
| unselectAllText | string | true | Text label for button shown when all checkboxes are checked, for example, “Unselect all” |
| context | string | true | Visually hidden text appended to the button label to add context for screen readers. For example, “Select all of the following checkboxes”. |
HTML
<div class="ons-panel ons-panel--error ons-panel--no-title" id="dietary-error-checkbox">
<span class="ons-panel__assistive-text ons-u-vh">Error: </span>
<div class="ons-panel__body">
<p class="ons-panel__error">
<strong>Enter your dietary requirements</strong>
</p>
<div class="ons-input-items">
<p class="ons-checkboxes__label"> Select all that apply </p>
<div class="ons-checkboxes__items">
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="gluten-free-checkbox-error" class="ons-checkbox__input ons-js-checkbox"
value="gluten-free" />
<label class=" ons-checkbox__label" for="gluten-free-checkbox-error"
id="gluten-free-checkbox-error-label">Gluten free</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="lactose-intolerant-checkbox-error" class="ons-checkbox__input ons-js-checkbox"
value="lactose-intolerant" />
<label class=" ons-checkbox__label" for="lactose-intolerant-checkbox-error"
id="lactose-intolerant-checkbox-error-label">Lactose intolerant</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="vegan-checkbox-error" class="ons-checkbox__input ons-js-checkbox"
value="vegan" />
<label class=" ons-checkbox__label" for="vegan-checkbox-error" id="vegan-checkbox-error-label">Vegan</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="vegetarian-checkbox-error" class="ons-checkbox__input ons-js-checkbox"
value="vegetarian" />
<label class=" ons-checkbox__label" for="vegetarian-checkbox-error"
id="vegetarian-checkbox-error-label">Vegetarian</label>
</span>
</span>
<br />
<span class="ons-checkboxes__item">
<span class="ons-checkbox">
<input type="checkbox" id="other-checkbox-error" class="ons-checkbox__input ons-js-checkbox ons-js-other"
value="other" checked aria-controls="other-checkbox-error-other-wrap" aria-haspopup="true" />
<label class=" ons-checkbox__label" for="other-checkbox-error" id="other-checkbox-error-label">Other</label>
<span class="ons-checkbox__other" id="other-checkbox-error-other-wrap">
<label class="ons-label ons-u-fw-n" for="other-textbox-checbox-error"
id="other-textbox-checbox-error-label">Enter dietary requirements</label>
<input type="text" id="other-textbox-checbox-error"
class="ons-input ons-input--text ons-input-type__input ons-input--error ons-input--w-auto"
name="other-answer" />
</span>
</span>
</span>
</div>
</div>
</div>
</div>If no checkbox options have been selected
Use “Select [whatever it is]”.
For example, “Select your dietary requirements”.
If “checkbox with input” is selected but the input field is empty
Use “Enter your [whatever it is]”.
For example, “Enter your sexual orientation”.
If “checkbox with drop-down” is selected but a drop-down option has not been selected
Use “Select [whatever topic the drop-down is asking for]”.
For example, “Select the time of day you would like us to contact you”.
Help improve this page
Let us know how we could improve this page, or share your user research findings. Discuss the ‘Checkboxes’ component on GitHub (opens in a new tab)