Skip to main content

Form elements - Checkboxes

Use checkboxes to let users select 1 or more options on a form.

Checkboxes updates

Added smaller checkboxes in version 10.1

Made "breaking code changes" to checkboxes in version 10

Open this default checkboxes example in a new tab 
<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 id="example-hint" class="nhsuk-hint">
      Select all options that are relevant to you
    </div>
    <div class="nhsuk-checkboxes" data-module="nhsuk-checkboxes">
      <div class="nhsuk-checkboxes__item">
        <input class="nhsuk-checkboxes__input" id="example" name="example" type="checkbox" value="email">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="example">
          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>
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.

Nunjucks arguments for default checkboxes
Name Type Required Description
id string false The ID of the checkboxes component.
describedBy string false One or more element IDs to add to the input aria-describedby attribute without a fieldset, used to provide additional descriptive information for screenreader users.
fieldset object false Can be used to add a fieldset to the checkboxes component.
hint object false Can be used to add a hint to the checkboxes component.
errorMessage object false Can be used to add an error message to the checkboxes component. The error message component will not display if you use a falsy value for errorMessage, for example false or null.
formGroup object false Additional options for the form group containing the checkboxes component.
formGroup{}.classes string false Classes to add to the form group (for example to show error state for the whole group).
formGroup{}.attributes object false HTML attributes (for example data attributes) to add to the form group.
formGroup{}.beforeInputs object false Content to add before all checkbox items within the checkboxes component.
formGroup{}.beforeInputs{}.text string true Text to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.beforeInputs{}.html string true HTML to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs object false Content to add after all checkbox items within the checkboxes component.
formGroup{}.afterInputs{}.text string true Text to add after all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs{}.html string true HTML to add after all checkbox items. If html is provided, the text option will be ignored.
idPrefix string false Optional prefix. This is used to prefix the id attribute for each checkbox item input, hint and error message, separated by -. Defaults to the name option value.
name string true Name attribute for all checkbox items.
items array true The checkbox items within the checkboxes component.
items[].text string true If html is set, this is not required. Text to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].html string true If text is set, this is not required. HTML to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].id string false Specific ID attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
items[].name string false Specific name for the checkbox item. If omitted, then component global name string will be applied.
items[].value string true Value for the checkbox input.
items[].label object false Subset of options for the label used by each checkbox item within the checkboxes component.
items[].label{}.classes string false Classes to add to the label tag.
items[].label{}.attributes object false HTML attributes (for example data attributes) to add to the label tag.
items[].hint object false Can be used to add a hint to each checkbox item within the checkboxes component.
items[].divider string false Divider text to separate checkbox items, for example the text "or".
items[].checked boolean false Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
items[].conditional object false Provide additional content to reveal when the checkbox is checked.
items[].conditional{}.html string true The HTML to reveal when the checkbox is checked.
items[].disabled boolean false If true, checkbox will be disabled.
items[].attributes object false HTML attributes (for example data attributes) to add to the checkbox input tag.
items[].exclusive boolean false 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.
items[].exclusiveGroup string false 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.
values array false Array of values for checkboxes which should be checked when the page loads. Use this as an alternative to setting the checked option on each individual item.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the checkboxes container. 
{% from 'checkboxes/macro.njk' import checkboxes %}

{{ 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"
    }
  ]
}) }}

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

Position checkboxes to the left of their labels. This makes them easier to find, especially for users of screen magnifiers.

Do not pre-select checkbox options as this makes it more likely that users will:

  • not realise they've missed a question
  • submit the wrong answer

Order checkbox options alphabetically by default. In some cases, it's helpful to order them from most-to-least common options, for example, by population size. But be careful, as this can reinforce bias. If in doubt, order alphabetically.

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?".

Read more about using fieldset.

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". Read more about hint text.

Open this hint checkboxes example in a new tab 
<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 id="contact-hint" class="nhsuk-hint">
      Select all options that are relevant to you
    </div>
    <div class="nhsuk-checkboxes" data-module="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>
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.

Nunjucks arguments for hint checkboxes
Name Type Required Description
id string false The ID of the checkboxes component.
describedBy string false One or more element IDs to add to the input aria-describedby attribute without a fieldset, used to provide additional descriptive information for screenreader users.
fieldset object false Can be used to add a fieldset to the checkboxes component.
hint object false Can be used to add a hint to the checkboxes component.
errorMessage object false Can be used to add an error message to the checkboxes component. The error message component will not display if you use a falsy value for errorMessage, for example false or null.
formGroup object false Additional options for the form group containing the checkboxes component.
formGroup{}.classes string false Classes to add to the form group (for example to show error state for the whole group).
formGroup{}.attributes object false HTML attributes (for example data attributes) to add to the form group.
formGroup{}.beforeInputs object false Content to add before all checkbox items within the checkboxes component.
formGroup{}.beforeInputs{}.text string true Text to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.beforeInputs{}.html string true HTML to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs object false Content to add after all checkbox items within the checkboxes component.
formGroup{}.afterInputs{}.text string true Text to add after all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs{}.html string true HTML to add after all checkbox items. If html is provided, the text option will be ignored.
idPrefix string false Optional prefix. This is used to prefix the id attribute for each checkbox item input, hint and error message, separated by -. Defaults to the name option value.
name string true Name attribute for all checkbox items.
items array true The checkbox items within the checkboxes component.
items[].text string true If html is set, this is not required. Text to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].html string true If text is set, this is not required. HTML to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].id string false Specific ID attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
items[].name string false Specific name for the checkbox item. If omitted, then component global name string will be applied.
items[].value string true Value for the checkbox input.
items[].label object false Subset of options for the label used by each checkbox item within the checkboxes component.
items[].label{}.classes string false Classes to add to the label tag.
items[].label{}.attributes object false HTML attributes (for example data attributes) to add to the label tag.
items[].hint object false Can be used to add a hint to each checkbox item within the checkboxes component.
items[].divider string false Divider text to separate checkbox items, for example the text "or".
items[].checked boolean false Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
items[].conditional object false Provide additional content to reveal when the checkbox is checked.
items[].conditional{}.html string true The HTML to reveal when the checkbox is checked.
items[].disabled boolean false If true, checkbox will be disabled.
items[].attributes object false HTML attributes (for example data attributes) to add to the checkbox input tag.
items[].exclusive boolean false 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.
items[].exclusiveGroup string false 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.
values array false Array of values for checkboxes which should be checked when the page loads. Use this as an alternative to setting the checked option on each individual item.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the checkboxes container. 
{% from 'checkboxes/macro.njk' import checkboxes %}

{{ 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"
    }
  ]
}) }}

Checkbox items with hints

You can add hints to checkbox items to provide additional information about the options.

Open this items with hints checkboxes example in a new tab 
<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 id="nationality-hint" class="nhsuk-hint">
      If you have dual nationality, select all options that are relevant to you
    </div>
    <div class="nhsuk-checkboxes" data-module="nhsuk-checkboxes">
      <div class="nhsuk-checkboxes__item">
        <input class="nhsuk-checkboxes__input" id="nationality" name="nationality" type="checkbox" value="british" aria-describedby="nationality-item-hint">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="nationality">
          British
        </label>
        <div id="nationality-item-hint" class="nhsuk-hint nhsuk-checkboxes__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>
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.

Nunjucks arguments for items with hints checkboxes
Name Type Required Description
id string false The ID of the checkboxes component.
describedBy string false One or more element IDs to add to the input aria-describedby attribute without a fieldset, used to provide additional descriptive information for screenreader users.
fieldset object false Can be used to add a fieldset to the checkboxes component.
hint object false Can be used to add a hint to the checkboxes component.
errorMessage object false Can be used to add an error message to the checkboxes component. The error message component will not display if you use a falsy value for errorMessage, for example false or null.
formGroup object false Additional options for the form group containing the checkboxes component.
formGroup{}.classes string false Classes to add to the form group (for example to show error state for the whole group).
formGroup{}.attributes object false HTML attributes (for example data attributes) to add to the form group.
formGroup{}.beforeInputs object false Content to add before all checkbox items within the checkboxes component.
formGroup{}.beforeInputs{}.text string true Text to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.beforeInputs{}.html string true HTML to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs object false Content to add after all checkbox items within the checkboxes component.
formGroup{}.afterInputs{}.text string true Text to add after all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs{}.html string true HTML to add after all checkbox items. If html is provided, the text option will be ignored.
idPrefix string false Optional prefix. This is used to prefix the id attribute for each checkbox item input, hint and error message, separated by -. Defaults to the name option value.
name string true Name attribute for all checkbox items.
items array true The checkbox items within the checkboxes component.
items[].text string true If html is set, this is not required. Text to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].html string true If text is set, this is not required. HTML to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].id string false Specific ID attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
items[].name string false Specific name for the checkbox item. If omitted, then component global name string will be applied.
items[].value string true Value for the checkbox input.
items[].label object false Subset of options for the label used by each checkbox item within the checkboxes component.
items[].label{}.classes string false Classes to add to the label tag.
items[].label{}.attributes object false HTML attributes (for example data attributes) to add to the label tag.
items[].hint object false Can be used to add a hint to each checkbox item within the checkboxes component.
items[].divider string false Divider text to separate checkbox items, for example the text "or".
items[].checked boolean false Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
items[].conditional object false Provide additional content to reveal when the checkbox is checked.
items[].conditional{}.html string true The HTML to reveal when the checkbox is checked.
items[].disabled boolean false If true, checkbox will be disabled.
items[].attributes object false HTML attributes (for example data attributes) to add to the checkbox input tag.
items[].exclusive boolean false 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.
items[].exclusiveGroup string false 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.
values array false Array of values for checkboxes which should be checked when the page loads. Use this as an alternative to setting the checked option on each individual item.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the checkboxes container. 
{% from 'checkboxes/macro.njk' import checkboxes %}

{{ 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"
    }
  ]
}) }}

Add 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.

Open this none option checkboxes example in a new tab 
<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 id="symptoms-hint" class="nhsuk-hint">
      Select all the symptoms you have
    </div>
    <div class="nhsuk-checkboxes" data-module="nhsuk-checkboxes">
      <div class="nhsuk-checkboxes__item">
        <input class="nhsuk-checkboxes__input" id="symptoms" name="symptoms" type="checkbox" value="sorethroat" data-checkbox-exclusive-group="symptoms-list">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="symptoms">
          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>
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.

Nunjucks arguments for none option checkboxes
Name Type Required Description
id string false The ID of the checkboxes component.
describedBy string false One or more element IDs to add to the input aria-describedby attribute without a fieldset, used to provide additional descriptive information for screenreader users.
fieldset object false Can be used to add a fieldset to the checkboxes component.
hint object false Can be used to add a hint to the checkboxes component.
errorMessage object false Can be used to add an error message to the checkboxes component. The error message component will not display if you use a falsy value for errorMessage, for example false or null.
formGroup object false Additional options for the form group containing the checkboxes component.
formGroup{}.classes string false Classes to add to the form group (for example to show error state for the whole group).
formGroup{}.attributes object false HTML attributes (for example data attributes) to add to the form group.
formGroup{}.beforeInputs object false Content to add before all checkbox items within the checkboxes component.
formGroup{}.beforeInputs{}.text string true Text to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.beforeInputs{}.html string true HTML to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs object false Content to add after all checkbox items within the checkboxes component.
formGroup{}.afterInputs{}.text string true Text to add after all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs{}.html string true HTML to add after all checkbox items. If html is provided, the text option will be ignored.
idPrefix string false Optional prefix. This is used to prefix the id attribute for each checkbox item input, hint and error message, separated by -. Defaults to the name option value.
name string true Name attribute for all checkbox items.
items array true The checkbox items within the checkboxes component.
items[].text string true If html is set, this is not required. Text to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].html string true If text is set, this is not required. HTML to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].id string false Specific ID attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
items[].name string false Specific name for the checkbox item. If omitted, then component global name string will be applied.
items[].value string true Value for the checkbox input.
items[].label object false Subset of options for the label used by each checkbox item within the checkboxes component.
items[].label{}.classes string false Classes to add to the label tag.
items[].label{}.attributes object false HTML attributes (for example data attributes) to add to the label tag.
items[].hint object false Can be used to add a hint to each checkbox item within the checkboxes component.
items[].divider string false Divider text to separate checkbox items, for example the text "or".
items[].checked boolean false Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
items[].conditional object false Provide additional content to reveal when the checkbox is checked.
items[].conditional{}.html string true The HTML to reveal when the checkbox is checked.
items[].disabled boolean false If true, checkbox will be disabled.
items[].attributes object false HTML attributes (for example data attributes) to add to the checkbox input tag.
items[].exclusive boolean false 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.
items[].exclusiveGroup string false 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.
values array false Array of values for checkboxes which should be checked when the page loads. Use this as an alternative to setting the checked option on each individual item.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the checkboxes container. 
{% from 'checkboxes/macro.njk' import checkboxes %}

{{ 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"
    }
  ]
}) }}

If JavaScript is unavailable, and a user selects both the "none" checkbox and another checkbox, display an error message.

Conditionally revealing a related question

You can add a conditionally revealing related question to checkboxes, so users only see the question 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.

Open this conditional checkboxes example in a new tab 
<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 id="contact-hint" class="nhsuk-hint">
      Select all options that are relevant to you
    </div>
    <div class="nhsuk-checkboxes" data-module="nhsuk-checkboxes">
      <div class="nhsuk-checkboxes__item">
        <input class="nhsuk-checkboxes__input" id="contact" name="contact" type="checkbox" value="email" aria-controls="conditional-contact">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="contact">
          Email
        </label>
      </div>
      <div class="nhsuk-checkboxes__conditional nhsuk-checkboxes__conditional--hidden" id="conditional-contact">
        <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">
        <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">
        <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>
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.

Nunjucks arguments for conditional checkboxes
Name Type Required Description
id string false The ID of the checkboxes component.
describedBy string false One or more element IDs to add to the input aria-describedby attribute without a fieldset, used to provide additional descriptive information for screenreader users.
fieldset object false Can be used to add a fieldset to the checkboxes component.
hint object false Can be used to add a hint to the checkboxes component.
errorMessage object false Can be used to add an error message to the checkboxes component. The error message component will not display if you use a falsy value for errorMessage, for example false or null.
formGroup object false Additional options for the form group containing the checkboxes component.
formGroup{}.classes string false Classes to add to the form group (for example to show error state for the whole group).
formGroup{}.attributes object false HTML attributes (for example data attributes) to add to the form group.
formGroup{}.beforeInputs object false Content to add before all checkbox items within the checkboxes component.
formGroup{}.beforeInputs{}.text string true Text to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.beforeInputs{}.html string true HTML to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs object false Content to add after all checkbox items within the checkboxes component.
formGroup{}.afterInputs{}.text string true Text to add after all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs{}.html string true HTML to add after all checkbox items. If html is provided, the text option will be ignored.
idPrefix string false Optional prefix. This is used to prefix the id attribute for each checkbox item input, hint and error message, separated by -. Defaults to the name option value.
name string true Name attribute for all checkbox items.
items array true The checkbox items within the checkboxes component.
items[].text string true If html is set, this is not required. Text to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].html string true If text is set, this is not required. HTML to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].id string false Specific ID attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
items[].name string false Specific name for the checkbox item. If omitted, then component global name string will be applied.
items[].value string true Value for the checkbox input.
items[].label object false Subset of options for the label used by each checkbox item within the checkboxes component.
items[].label{}.classes string false Classes to add to the label tag.
items[].label{}.attributes object false HTML attributes (for example data attributes) to add to the label tag.
items[].hint object false Can be used to add a hint to each checkbox item within the checkboxes component.
items[].divider string false Divider text to separate checkbox items, for example the text "or".
items[].checked boolean false Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
items[].conditional object false Provide additional content to reveal when the checkbox is checked.
items[].conditional{}.html string true The HTML to reveal when the checkbox is checked.
items[].disabled boolean false If true, checkbox will be disabled.
items[].attributes object false HTML attributes (for example data attributes) to add to the checkbox input tag.
items[].exclusive boolean false 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.
items[].exclusiveGroup string false 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.
values array false Array of values for checkboxes which should be checked when the page loads. Use this as an alternative to setting the checked option on each individual item.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the checkboxes container. 
{% 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 -%}

{{ 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
      }
    }
  ]
}) }}

Keep it simple. If you need to add a lot of content, consider showing it on the next page in the process instead.

Only conditionally reveal questions. Do not show or hide anything that is not a question.

Known issues

Users are not always notified when a conditionally revealed question is shown or hidden. This fails WCAG 2.2 success criterion 4.1.2 name, role, value (W3C).

However, GOV.UK found that screen reader users did not have difficulty answering a conditionally revealed question as long as it’s simple. It confused users when they conditionally revealed complicated questions.

Smaller checkboxes

Open this smaller checkboxes example in a new tab 
<div class="nhsuk-form-group">
  <fieldset class="nhsuk-fieldset">
    <legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--m">
      <h1 class="nhsuk-fieldset__heading">
        Care setting
      </h1>
    </legend>
    <div class="nhsuk-checkboxes nhsuk-checkboxes--small" data-module="nhsuk-checkboxes">
      <div class="nhsuk-checkboxes__item">
        <input class="nhsuk-checkboxes__input" id="example" name="example" type="checkbox" value="ambulance or urgent and emergency care">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="example">
          Ambulance or urgent and emergency care
        </label>
      </div>
      <div class="nhsuk-checkboxes__item">
        <input class="nhsuk-checkboxes__input" id="example-2" name="example" type="checkbox" value="care home">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="example-2">
          Care home
        </label>
      </div>
      <div class="nhsuk-checkboxes__item">
        <input class="nhsuk-checkboxes__input" id="example-3" name="example" type="checkbox" value="community health">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="example-3">
          Community health
        </label>
      </div>
      <div class="nhsuk-checkboxes__item">
        <input class="nhsuk-checkboxes__input" id="example-4" name="example" type="checkbox" value="dentistry">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="example-4">
          Dentistry
        </label>
      </div>
    </div>
  </fieldset>
</div>
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.

Nunjucks arguments for smaller checkboxes
Name Type Required Description
id string false The ID of the checkboxes component.
describedBy string false One or more element IDs to add to the input aria-describedby attribute without a fieldset, used to provide additional descriptive information for screenreader users.
fieldset object false Can be used to add a fieldset to the checkboxes component.
hint object false Can be used to add a hint to the checkboxes component.
errorMessage object false Can be used to add an error message to the checkboxes component. The error message component will not display if you use a falsy value for errorMessage, for example false or null.
formGroup object false Additional options for the form group containing the checkboxes component.
formGroup{}.classes string false Classes to add to the form group (for example to show error state for the whole group).
formGroup{}.attributes object false HTML attributes (for example data attributes) to add to the form group.
formGroup{}.beforeInputs object false Content to add before all checkbox items within the checkboxes component.
formGroup{}.beforeInputs{}.text string true Text to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.beforeInputs{}.html string true HTML to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs object false Content to add after all checkbox items within the checkboxes component.
formGroup{}.afterInputs{}.text string true Text to add after all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs{}.html string true HTML to add after all checkbox items. If html is provided, the text option will be ignored.
idPrefix string false Optional prefix. This is used to prefix the id attribute for each checkbox item input, hint and error message, separated by -. Defaults to the name option value.
name string true Name attribute for all checkbox items.
items array true The checkbox items within the checkboxes component.
items[].text string true If html is set, this is not required. Text to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].html string true If text is set, this is not required. HTML to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].id string false Specific ID attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
items[].name string false Specific name for the checkbox item. If omitted, then component global name string will be applied.
items[].value string true Value for the checkbox input.
items[].label object false Subset of options for the label used by each checkbox item within the checkboxes component.
items[].label{}.classes string false Classes to add to the label tag.
items[].label{}.attributes object false HTML attributes (for example data attributes) to add to the label tag.
items[].hint object false Can be used to add a hint to each checkbox item within the checkboxes component.
items[].divider string false Divider text to separate checkbox items, for example the text "or".
items[].checked boolean false Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
items[].conditional object false Provide additional content to reveal when the checkbox is checked.
items[].conditional{}.html string true The HTML to reveal when the checkbox is checked.
items[].disabled boolean false If true, checkbox will be disabled.
items[].attributes object false HTML attributes (for example data attributes) to add to the checkbox input tag.
items[].exclusive boolean false 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.
items[].exclusiveGroup string false 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.
values array false Array of values for checkboxes which should be checked when the page loads. Use this as an alternative to setting the checked option on each individual item.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the checkboxes container. 
{% from 'checkboxes/macro.njk' import checkboxes %}

{{ checkboxes({
  idPrefix: "example",
  name: "example",
  fieldset: {
    legend: {
      text: "Care setting",
      classes: "nhsuk-fieldset__legend--m",
      isPageHeading: true
    }
  },
  classes: "nhsuk-checkboxes--small",
  items: [
    {
      value: "ambulance or urgent and emergency care",
      text: "Ambulance or urgent and emergency care"
    },
    {
      value: "care home",
      text: "Care home"
    },
    {
      value: "community health",
      text: "Community health"
    },
    {
      value: "dentistry",
      text: "Dentistry"
    }
  ]
}) }}

Use standard-sized checkboxes in most cases.

You can use small checkboxes where you need something less visually prominent. For example, on:

  • a page of search results where users need to see and change search filters without distracting them from the results
  • on information-dense screens in services designed for repeat use, like staff-facing systems

Error messages

Error messages should be styled like this:

Open this error messages checkboxes example in a new tab 
<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 id="contact-hint" class="nhsuk-hint">
      Select all options that are relevant to you
    </div>
    <span id="contact-error" class="nhsuk-error-message">
      <span class="nhsuk-u-visually-hidden">Error:</span> Select how you like to be contacted
    </span>
    <div class="nhsuk-checkboxes" data-module="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>
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.

Nunjucks arguments for error messages checkboxes
Name Type Required Description
id string false The ID of the checkboxes component.
describedBy string false One or more element IDs to add to the input aria-describedby attribute without a fieldset, used to provide additional descriptive information for screenreader users.
fieldset object false Can be used to add a fieldset to the checkboxes component.
hint object false Can be used to add a hint to the checkboxes component.
errorMessage object false Can be used to add an error message to the checkboxes component. The error message component will not display if you use a falsy value for errorMessage, for example false or null.
formGroup object false Additional options for the form group containing the checkboxes component.
formGroup{}.classes string false Classes to add to the form group (for example to show error state for the whole group).
formGroup{}.attributes object false HTML attributes (for example data attributes) to add to the form group.
formGroup{}.beforeInputs object false Content to add before all checkbox items within the checkboxes component.
formGroup{}.beforeInputs{}.text string true Text to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.beforeInputs{}.html string true HTML to add before all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs object false Content to add after all checkbox items within the checkboxes component.
formGroup{}.afterInputs{}.text string true Text to add after all checkbox items. If html is provided, the text option will be ignored.
formGroup{}.afterInputs{}.html string true HTML to add after all checkbox items. If html is provided, the text option will be ignored.
idPrefix string false Optional prefix. This is used to prefix the id attribute for each checkbox item input, hint and error message, separated by -. Defaults to the name option value.
name string true Name attribute for all checkbox items.
items array true The checkbox items within the checkboxes component.
items[].text string true If html is set, this is not required. Text to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].html string true If text is set, this is not required. HTML to use within each checkbox item label. If html is provided, the text option will be ignored.
items[].id string false Specific ID attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
items[].name string false Specific name for the checkbox item. If omitted, then component global name string will be applied.
items[].value string true Value for the checkbox input.
items[].label object false Subset of options for the label used by each checkbox item within the checkboxes component.
items[].label{}.classes string false Classes to add to the label tag.
items[].label{}.attributes object false HTML attributes (for example data attributes) to add to the label tag.
items[].hint object false Can be used to add a hint to each checkbox item within the checkboxes component.
items[].divider string false Divider text to separate checkbox items, for example the text "or".
items[].checked boolean false Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
items[].conditional object false Provide additional content to reveal when the checkbox is checked.
items[].conditional{}.html string true The HTML to reveal when the checkbox is checked.
items[].disabled boolean false If true, checkbox will be disabled.
items[].attributes object false HTML attributes (for example data attributes) to add to the checkbox input tag.
items[].exclusive boolean false 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.
items[].exclusiveGroup string false 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.
values array false Array of values for checkboxes which should be checked when the page loads. Use this as an alternative to setting the checked option on each individual item.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the checkboxes container. 
{% from 'checkboxes/macro.njk' import checkboxes %}

{{ 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"
    }
  ]
}) }}

Follow:

Research

Our checkboxes are based on the GOV.UK design system. Read a GOV.UK blog post about their updates to radios and checkboxes.

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.

Feed back or share insights on GitHub

Read more about how to feed back or share insights.

If you have any questions, get in touch with the service manual team.

Updated: October 2025