Use checkboxes to let users select 1 or more options on a form.
<form>
<div class="nhsuk-form-group">
<fieldset class="nhsuk-fieldset" aria-describedby="example-hint">
<legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
<h1 class="nhsuk-fieldset__heading">
How would you like to be contacted?
</h1>
</legend>
<div class="nhsuk-hint" id="example-hint">
Select all options that are relevant to you.
</div>
<div class="nhsuk-checkboxes">
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="example-1" name="example" type="checkbox" value="email">
<label class="nhsuk-label nhsuk-checkboxes__label" for="example-1">
Email
</label>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="example-2" name="example" type="checkbox" value="phone">
<label class="nhsuk-label nhsuk-checkboxes__label" for="example-2">
Phone
</label>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="example-3" name="example" type="checkbox" value="text message">
<label class="nhsuk-label nhsuk-checkboxes__label" for="example-3">
Text message
</label>
</div>
</div>
</fieldset>
</div>
</form>
Nunjucks macro options
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
Some options are required for the macro to work; these are marked as "Required" in the option description.
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.
Name | Type | Required | Description |
---|---|---|---|
Name fieldset | Type object | Required false | Description Options for the fieldset component (for example legend). |
Name hint | Type object | Required false | Description Options for the hint component (for example text). |
Name errorMessage | Type object | Required false | Description Options for the error message component. |
Name idPrefix | Type string | Required false | Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead. |
Name name | Type string | Required true | Description Name attribute for all checkbox items. |
Name items | Type array | Required true | Description Array of checkbox items objects. |
Name items[].text | Type string | Required true | Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].html | Type string | Required true | Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].id | Type string | Required false | Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied. |
Name items[].name | Type string | Required false | Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied. |
Name items[].value | Type string | Required true | Description Value for the checkbox input. |
Name items[].divider | Type string | Required true | Description Optional divider text to separate checkbox items, for example the text "or". |
Name items[].hint | Type object | Required false | Description Provide hint to each checkbox item. |
Name items[].checked | Type boolean | Required false | Description If true, checkbox will be checked. |
Name items[].conditional | Type boolean | Required false | Description If true, content provided will be revealed when the item is checked. |
Name items[].conditional.html | Type string | Required false | Description Provide content for the conditional reveal. |
Name items[].disabled | Type boolean | Required false | Description If true, checkbox will be disabled. |
Name items[].attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the checkbox input tag. |
Name exclusive | Type boolean | Required false | Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked. |
Name exclusiveGroup | Type string | Required false | Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario. |
Name classes | Type string | Required false | Description Classes to add to the checkboxes container. |
Name attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the anchor tag. |
{% from 'checkboxes/macro.njk' import checkboxes %}
<form>
{{ checkboxes({
"idPrefix": "example",
"name": "example",
"fieldset": {
"legend": {
"text": "How would you like to be contacted?",
"classes": "nhsuk-fieldset__legend--l",
isPageHeading: true
}
},
"hint": {
"text": "Select all options that are relevant to you."
},
"items": [
{
"value": "email",
"text": "Email"
},
{
"value": "phone",
"text": "Phone"
},
{
"value": "text message",
"text": "Text message"
}
]
}) }}
</form>
When to use checkboxes
Use checkboxes when you need to help users:
- select more than 1 option from a list
- toggle a single option on or off
When not to use checkboxes
Do not use the checkboxes component if users can only choose 1 option from a selection. In this case, use a radio.
How to use checkboxes
Group checkboxes together in a <fieldset>
with a <legend>
that describes them. You can see an example at the top of this page. The legend is usually a question, like "How would you like to be contacted?".
If you're asking just 1 question per page as we recommend, you can set the contents of the <legend>
as the page heading. This is good practice as it means screen reader users will only hear the contents once.
Read more on the GOV.UK Design System about making labels and legends headings.
Checkboxes with hint text
Unlike with radios, users can select more than 1 option from a list of checkboxes. Do not assume that users will know how many options they can select.
Use hint text to give users help in context. For example, say "Select all the options that are relevant to you".
<form>
<div class="nhsuk-form-group">
<fieldset class="nhsuk-fieldset" aria-describedby="contact-hint">
<legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
<h1 class="nhsuk-fieldset__heading">
How would you like to be contacted?
</h1>
</legend>
<div class="nhsuk-hint" id="contact-hint">
Select all options that are relevant to you.
</div>
<div class="nhsuk-checkboxes">
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="contact" name="contact" type="checkbox" value="email">
<label class="nhsuk-label nhsuk-checkboxes__label" for="contact">
Email
</label>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="contact-2" name="contact" type="checkbox" value="phone">
<label class="nhsuk-label nhsuk-checkboxes__label" for="contact-2">
Phone
</label>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="contact-3" name="contact" type="checkbox" value="text message">
<label class="nhsuk-label nhsuk-checkboxes__label" for="contact-3">
Text message
</label>
</div>
</div>
</fieldset>
</div>
</form>
Nunjucks macro options
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
Some options are required for the macro to work; these are marked as "Required" in the option description.
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.
Name | Type | Required | Description |
---|---|---|---|
Name fieldset | Type object | Required false | Description Options for the fieldset component (for example legend). |
Name hint | Type object | Required false | Description Options for the hint component (for example text). |
Name errorMessage | Type object | Required false | Description Options for the error message component. |
Name idPrefix | Type string | Required false | Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead. |
Name name | Type string | Required true | Description Name attribute for all checkbox items. |
Name items | Type array | Required true | Description Array of checkbox items objects. |
Name items[].text | Type string | Required true | Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].html | Type string | Required true | Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].id | Type string | Required false | Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied. |
Name items[].name | Type string | Required false | Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied. |
Name items[].value | Type string | Required true | Description Value for the checkbox input. |
Name items[].divider | Type string | Required true | Description Optional divider text to separate checkbox items, for example the text "or". |
Name items[].hint | Type object | Required false | Description Provide hint to each checkbox item. |
Name items[].checked | Type boolean | Required false | Description If true, checkbox will be checked. |
Name items[].conditional | Type boolean | Required false | Description If true, content provided will be revealed when the item is checked. |
Name items[].conditional.html | Type string | Required false | Description Provide content for the conditional reveal. |
Name items[].disabled | Type boolean | Required false | Description If true, checkbox will be disabled. |
Name items[].attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the checkbox input tag. |
Name exclusive | Type boolean | Required false | Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked. |
Name exclusiveGroup | Type string | Required false | Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario. |
Name classes | Type string | Required false | Description Classes to add to the checkboxes container. |
Name attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the anchor tag. |
{% from 'checkboxes/macro.njk' import checkboxes %}
<form>
{{ checkboxes({
"idPrefix": "contact",
"name": "contact",
"fieldset": {
"legend": {
"text": "How would you like to be contacted?",
"classes": "nhsuk-fieldset__legend--l",
isPageHeading: true
}
},
"hint": {
"text": "Select all options that are relevant to you."
},
"items": [
{
"value": "email",
"text": "Email",
id: "contact"
},
{
"value": "phone",
"text": "Phone"
},
{
"value": "text message",
"text": "Text message"
}
]
}) }}
</form>
Checkbox items with hints
You can add hints to checkbox items to provide additional information about the options.
<form>
<div class="nhsuk-form-group">
<fieldset class="nhsuk-fieldset" aria-describedby="nationality-hint">
<legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
<h1 class="nhsuk-fieldset__heading">
What is your nationality?
</h1>
</legend>
<div class="nhsuk-hint" id="nationality-hint">
If you have dual nationality, select all options that are relevant to you.
</div>
<div class="nhsuk-checkboxes">
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="nationality-1" name="nationality" type="checkbox" value="british" aria-describedby="nationality-1-item-hint">
<label class="nhsuk-label nhsuk-checkboxes__label" for="nationality-1">
British
</label>
<div class="nhsuk-hint nhsuk-checkboxes__hint" id="nationality-1-item-hint">
including English, Scottish, Welsh and Northern Irish
</div>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="nationality-2" name="nationality" type="checkbox" value="irish">
<label class="nhsuk-label nhsuk-checkboxes__label" for="nationality-2">
Irish
</label>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="nationality-3" name="nationality" type="checkbox" value="other">
<label class="nhsuk-label nhsuk-checkboxes__label" for="nationality-3">
Citizen of another country
</label>
</div>
</div>
</fieldset>
</div>
</form>
Nunjucks macro options
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
Some options are required for the macro to work; these are marked as "Required" in the option description.
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.
Name | Type | Required | Description |
---|---|---|---|
Name fieldset | Type object | Required false | Description Options for the fieldset component (for example legend). |
Name hint | Type object | Required false | Description Options for the hint component (for example text). |
Name errorMessage | Type object | Required false | Description Options for the error message component. |
Name idPrefix | Type string | Required false | Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead. |
Name name | Type string | Required true | Description Name attribute for all checkbox items. |
Name items | Type array | Required true | Description Array of checkbox items objects. |
Name items[].text | Type string | Required true | Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].html | Type string | Required true | Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].id | Type string | Required false | Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied. |
Name items[].name | Type string | Required false | Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied. |
Name items[].value | Type string | Required true | Description Value for the checkbox input. |
Name items[].divider | Type string | Required true | Description Optional divider text to separate checkbox items, for example the text "or". |
Name items[].hint | Type object | Required false | Description Provide hint to each checkbox item. |
Name items[].checked | Type boolean | Required false | Description If true, checkbox will be checked. |
Name items[].conditional | Type boolean | Required false | Description If true, content provided will be revealed when the item is checked. |
Name items[].conditional.html | Type string | Required false | Description Provide content for the conditional reveal. |
Name items[].disabled | Type boolean | Required false | Description If true, checkbox will be disabled. |
Name items[].attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the checkbox input tag. |
Name exclusive | Type boolean | Required false | Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked. |
Name exclusiveGroup | Type string | Required false | Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario. |
Name classes | Type string | Required false | Description Classes to add to the checkboxes container. |
Name attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the anchor tag. |
{% from 'checkboxes/macro.njk' import checkboxes %}
<form>
{{ checkboxes({
idPrefix: "nationality",
name: "nationality",
fieldset: {
legend: {
text: "What is your nationality?",
isPageHeading: true,
classes: "nhsuk-fieldset__legend--l"
}
},
hint: {
text: "If you have dual nationality, select all options that are relevant to you."
},
items: [
{
value: "british",
text: "British",
hint: {
text: "including English, Scottish, Welsh and Northern Irish"
}
},
{
value: "irish",
text: "Irish"
},
{
value: "other",
text: "Citizen of another country"
}
]
}) }}
</form>
Conditionally revealing content
You can add conditionally revealing content to checkboxes, so users only see content when it's relevant to them.
For example, you could reveal a phone number input only when a user chooses to be contacted by phone.
<form>
<div class="nhsuk-form-group">
<fieldset class="nhsuk-fieldset" aria-describedby="contact-hint">
<legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
<h1 class="nhsuk-fieldset__heading">
How would you prefer to be contacted?
</h1>
</legend>
<div class="nhsuk-hint" id="contact-hint">
Select all options that are relevant to you.
</div>
<div class="nhsuk-checkboxes nhsuk-checkboxes--conditional">
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="contact-1" name="contact" type="checkbox" value="email" aria-controls="conditional-contact-1" aria-expanded="false">
<label class="nhsuk-label nhsuk-checkboxes__label" for="contact-1">
Email
</label>
</div>
<div class="nhsuk-checkboxes__conditional nhsuk-checkboxes__conditional--hidden" id="conditional-contact-1">
<div class="nhsuk-form-group">
<label class="nhsuk-label" for="email">
Email address
</label>
<input class="nhsuk-input nhsuk-u-width-two-thirds" id="email" name="email" type="text">
</div>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="contact-2" name="contact" type="checkbox" value="phone" aria-controls="conditional-contact-2" aria-expanded="false">
<label class="nhsuk-label nhsuk-checkboxes__label" for="contact-2">
Phone
</label>
</div>
<div class="nhsuk-checkboxes__conditional nhsuk-checkboxes__conditional--hidden" id="conditional-contact-2">
<div class="nhsuk-form-group">
<label class="nhsuk-label" for="phone">
Phone number
</label>
<input class="nhsuk-input nhsuk-u-width-two-thirds" id="phone" name="phone" type="text">
</div>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="contact-3" name="contact" type="checkbox" value="text" aria-controls="conditional-contact-3" aria-expanded="false">
<label class="nhsuk-label nhsuk-checkboxes__label" for="contact-3">
Text message
</label>
</div>
<div class="nhsuk-checkboxes__conditional nhsuk-checkboxes__conditional--hidden" id="conditional-contact-3">
<div class="nhsuk-form-group">
<label class="nhsuk-label" for="mobile">
Mobile phone number
</label>
<input class="nhsuk-input nhsuk-u-width-two-thirds" id="mobile" name="mobile" type="text">
</div>
</div>
</div>
</fieldset>
</div>
</form>
Nunjucks macro options
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
Some options are required for the macro to work; these are marked as "Required" in the option description.
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.
Name | Type | Required | Description |
---|---|---|---|
Name fieldset | Type object | Required false | Description Options for the fieldset component (for example legend). |
Name hint | Type object | Required false | Description Options for the hint component (for example text). |
Name errorMessage | Type object | Required false | Description Options for the error message component. |
Name idPrefix | Type string | Required false | Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead. |
Name name | Type string | Required true | Description Name attribute for all checkbox items. |
Name items | Type array | Required true | Description Array of checkbox items objects. |
Name items[].text | Type string | Required true | Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].html | Type string | Required true | Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].id | Type string | Required false | Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied. |
Name items[].name | Type string | Required false | Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied. |
Name items[].value | Type string | Required true | Description Value for the checkbox input. |
Name items[].divider | Type string | Required true | Description Optional divider text to separate checkbox items, for example the text "or". |
Name items[].hint | Type object | Required false | Description Provide hint to each checkbox item. |
Name items[].checked | Type boolean | Required false | Description If true, checkbox will be checked. |
Name items[].conditional | Type boolean | Required false | Description If true, content provided will be revealed when the item is checked. |
Name items[].conditional.html | Type string | Required false | Description Provide content for the conditional reveal. |
Name items[].disabled | Type boolean | Required false | Description If true, checkbox will be disabled. |
Name items[].attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the checkbox input tag. |
Name exclusive | Type boolean | Required false | Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked. |
Name exclusiveGroup | Type string | Required false | Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario. |
Name classes | Type string | Required false | Description Classes to add to the checkboxes container. |
Name attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the anchor tag. |
{% from 'checkboxes/macro.njk' import checkboxes %}
{% from 'input/macro.njk' import input %}
{% set emailHtml %}
{{ input({
id: "email",
name: "email",
classes: "nhsuk-u-width-two-thirds",
label: {
text: "Email address"
}
}) }}
{% endset -%}
{% set phoneHtml %}
{{ input({
id: "phone",
name: "phone",
classes: "nhsuk-u-width-two-thirds",
label: {
text: "Phone number"
}
}) }}
{% endset -%}
{% set mobileHtml %}
{{ input({
id: "mobile",
name: "mobile",
classes: "nhsuk-u-width-two-thirds",
label: {
text: "Mobile phone number"
}
}) }}
{% endset -%}
<form>
{{ checkboxes({
"idPrefix": "contact",
"name": "contact",
"fieldset": {
"legend": {
"text": "How would you prefer to be contacted?",
"classes": "nhsuk-fieldset__legend--l",
"isPageHeading": "true"
}
},
"hint": {
"text": "Select all options that are relevant to you."
},
"items": [
{
"value": "email",
"text": "Email",
"conditional": {
"html": emailHtml
}
},
{
"value": "phone",
"text": "Phone",
"conditional": {
"html": phoneHtml
}
},
{
"value": "text",
"text": "Text message",
"conditional": {
"html": mobileHtml
}
}
]
}) }}
</form>
Keep it simple. If you need to add a lot of content, consider showing it on the next page in the process instead.
Adding an option for "none"
You can give users the option to say none of the other options apply to them.
This option means users need to actively select "none" rather than leave all the boxes unchecked, which makes sure they do not skip the question by accident.
Remember to start by asking 1 question per page. You might be able to remove the need for a "none" option by asking the user a better question or by using filter questions to filter users out beforehand.
Show the "none" option last. Separate it from the other options using a divider, normally the word "or".
Write a label that repeats the key part of the question. For example, for the question "Do you have any of these symptoms?", say "No, I do not have any of these symptoms". Avoid phrases like "none of the above" because this is a visual reference and might be hard for people who use screen readers to understand.
To enable some JavaScript that unchecks all other checkboxes when the user clicks "none", add the data-checkbox-exclusive
behaviour to the "none" checkbox.
<form>
<div class="nhsuk-form-group">
<fieldset class="nhsuk-fieldset" aria-describedby="symptoms-hint">
<legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
<h1 class="nhsuk-fieldset__heading">
Do you have any of these symptoms?
</h1>
</legend>
<div class="nhsuk-hint" id="symptoms-hint">
Select all the symptoms you have.
</div>
<div class="nhsuk-checkboxes">
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="symptoms-1" name="symptoms" type="checkbox" value="sorethroat" data-checkbox-exclusive-group="symptoms-list">
<label class="nhsuk-label nhsuk-checkboxes__label" for="symptoms-1">
Sore throat
</label>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="symptoms-2" name="symptoms" type="checkbox" value="runnynose" data-checkbox-exclusive-group="symptoms-list">
<label class="nhsuk-label nhsuk-checkboxes__label" for="symptoms-2">
Runny nose
</label>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="symptoms-3" name="symptoms" type="checkbox" value="muscleorjointpain" data-checkbox-exclusive-group="symptoms-list">
<label class="nhsuk-label nhsuk-checkboxes__label" for="symptoms-3">
Muscle or joint pain
</label>
</div>
<div class="nhsuk-checkboxes__divider">or</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="symptoms-5" name="symptoms" type="checkbox" value="none" data-checkbox-exclusive data-checkbox-exclusive-group="symptoms-list">
<label class="nhsuk-label nhsuk-checkboxes__label" for="symptoms-5">
No, I do not have any of these symptoms
</label>
</div>
</div>
</fieldset>
</div>
</form>
Nunjucks macro options
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
Some options are required for the macro to work; these are marked as "Required" in the option description.
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.
Name | Type | Required | Description |
---|---|---|---|
Name fieldset | Type object | Required false | Description Options for the fieldset component (for example legend). |
Name hint | Type object | Required false | Description Options for the hint component (for example text). |
Name errorMessage | Type object | Required false | Description Options for the error message component. |
Name idPrefix | Type string | Required false | Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead. |
Name name | Type string | Required true | Description Name attribute for all checkbox items. |
Name items | Type array | Required true | Description Array of checkbox items objects. |
Name items[].text | Type string | Required true | Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].html | Type string | Required true | Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].id | Type string | Required false | Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied. |
Name items[].name | Type string | Required false | Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied. |
Name items[].value | Type string | Required true | Description Value for the checkbox input. |
Name items[].divider | Type string | Required true | Description Optional divider text to separate checkbox items, for example the text "or". |
Name items[].hint | Type object | Required false | Description Provide hint to each checkbox item. |
Name items[].checked | Type boolean | Required false | Description If true, checkbox will be checked. |
Name items[].conditional | Type boolean | Required false | Description If true, content provided will be revealed when the item is checked. |
Name items[].conditional.html | Type string | Required false | Description Provide content for the conditional reveal. |
Name items[].disabled | Type boolean | Required false | Description If true, checkbox will be disabled. |
Name items[].attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the checkbox input tag. |
Name exclusive | Type boolean | Required false | Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked. |
Name exclusiveGroup | Type string | Required false | Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario. |
Name classes | Type string | Required false | Description Classes to add to the checkboxes container. |
Name attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the anchor tag. |
{% from 'checkboxes/macro.njk' import checkboxes %}
<form>
{{ checkboxes({
idPrefix: "symptoms",
name: "symptoms",
fieldset: {
legend: {
text: "Do you have any of these symptoms?",
isPageHeading: true,
classes: "nhsuk-fieldset__legend--l"
}
},
hint: {
text: "Select all the symptoms you have."
},
items: [
{
value: "sorethroat",
text: "Sore throat",
exclusiveGroup: "symptoms-list"
},
{
value: "runnynose",
text: "Runny nose",
exclusiveGroup: "symptoms-list"
},
{
value: "muscleorjointpain",
text: "Muscle or joint pain",
exclusiveGroup: "symptoms-list"
},
{
divider: "or"
},
{
value: "none",
text: "No, I do not have any of these symptoms",
exclusive: true,
exclusiveGroup: "symptoms-list"
}
]
}) }}
</form>
If JavaScript is unavailable, and a user selects both the "none" checkbox and another checkbox, display an error message.
Error messages
Error messages should be styled like this:
<form>
<div class="nhsuk-form-group nhsuk-form-group--error">
<fieldset class="nhsuk-fieldset" aria-describedby="contact-hint contact-error">
<legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
<h1 class="nhsuk-fieldset__heading">
How would you like to be contacted?
</h1>
</legend>
<div class="nhsuk-hint" id="contact-hint">
Select all options that are relevant to you.
</div>
<span class="nhsuk-error-message" id="contact-error">
<span class="nhsuk-u-visually-hidden">Error:</span> Select how you like to be contacted
</span>
<div class="nhsuk-checkboxes">
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="contact" name="contact" type="checkbox" value="email">
<label class="nhsuk-label nhsuk-checkboxes__label" for="contact">
Email
</label>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="contact-2" name="contact" type="checkbox" value="phone">
<label class="nhsuk-label nhsuk-checkboxes__label" for="contact-2">
Phone
</label>
</div>
<div class="nhsuk-checkboxes__item">
<input class="nhsuk-checkboxes__input" id="contact-3" name="contact" type="checkbox" value="text message">
<label class="nhsuk-label nhsuk-checkboxes__label" for="contact-3">
Text message
</label>
</div>
</div>
</fieldset>
</div>
</form>
Nunjucks macro options
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
Some options are required for the macro to work; these are marked as "Required" in the option description.
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.
Name | Type | Required | Description |
---|---|---|---|
Name fieldset | Type object | Required false | Description Options for the fieldset component (for example legend). |
Name hint | Type object | Required false | Description Options for the hint component (for example text). |
Name errorMessage | Type object | Required false | Description Options for the error message component. |
Name idPrefix | Type string | Required false | Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead. |
Name name | Type string | Required true | Description Name attribute for all checkbox items. |
Name items | Type array | Required true | Description Array of checkbox items objects. |
Name items[].text | Type string | Required true | Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].html | Type string | Required true | Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored. |
Name items[].id | Type string | Required false | Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied. |
Name items[].name | Type string | Required false | Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied. |
Name items[].value | Type string | Required true | Description Value for the checkbox input. |
Name items[].divider | Type string | Required true | Description Optional divider text to separate checkbox items, for example the text "or". |
Name items[].hint | Type object | Required false | Description Provide hint to each checkbox item. |
Name items[].checked | Type boolean | Required false | Description If true, checkbox will be checked. |
Name items[].conditional | Type boolean | Required false | Description If true, content provided will be revealed when the item is checked. |
Name items[].conditional.html | Type string | Required false | Description Provide content for the conditional reveal. |
Name items[].disabled | Type boolean | Required false | Description If true, checkbox will be disabled. |
Name items[].attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the checkbox input tag. |
Name exclusive | Type boolean | Required false | Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked. |
Name exclusiveGroup | Type string | Required false | Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario. |
Name classes | Type string | Required false | Description Classes to add to the checkboxes container. |
Name attributes | Type object | Required false | Description HTML attributes (for example data attributes) to add to the anchor tag. |
{% from 'checkboxes/macro.njk' import checkboxes %}
<form>
{{ checkboxes({
"idPrefix": "contact",
"name": "contact",
"fieldset": {
"legend": {
"text": "How would you like to be contacted?",
"classes": "nhsuk-fieldset__legend--l",
isPageHeading: true
}
},
"hint": {
"text": "Select all options that are relevant to you."
},
"errorMessage": {
"text": "Select how you like to be contacted"
},
"items": [
{
"value": "email",
"text": "Email",
id: "contact"
},
{
"value": "phone",
"text": "Phone"
},
{
"value": "text message",
"text": "Text message"
}
]
}) }}
</form>
Follow:
Research
Our checkboxes are based on the GOV.UK Design System. Read more about how GOV.UK developed and tested them.
Help us improve this guidance
Share insights or feedback and take part in the discussion. We use GitHub as a collaboration space. All the information on it is open to the public.
Read more about how to feedback or share insights.
If you have any questions, get in touch with the service manual team.
Updated: January 2022