Skip to main content

Form elements – Checkboxes

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

Information: Version 10

Checkboxes updated in August 2025

See breaking code updates to checkboxes in version 10

Open this example in a new tab: checkboxes 
<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 do you want to be contacted about this?
      </h1>
    </legend>
    <div class="nhsuk-hint" id="example-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. Deprecated options are marked as "Deprecated".

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.

Primary options
Name Type Description
id string The ID of the checkboxes component.
describedBy string 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 Can be used to add a fieldset to the checkboxes component. See macro options for fieldset.
hint object Can be used to add a hint to the checkboxes component. See macro options for hint.
errorMessage object 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. See macro options for errorMessage.
formGroup object Additional options for the form group containing the checkboxes component. See macro options for formGroup.
idPrefix string 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 Required. The name attribute for all checkbox items.
items array Required. The checkbox items within the checkboxes component. See macro options for items.
values array 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.
small boolean If set to true, small checkboxes will be used.
classes string Classes to add to the checkboxes container.
attributes object HTML attributes (for example data attributes) to add to the checkboxes container.
Options for formGroup object
Name Type Description
classes string Classes to add to the form group (for example to show error state for the whole group).
attributes object HTML attributes (for example data attributes) to add to the form group.
beforeInputs object Content to add before all checkbox items within the checkboxes component. See macro options for formGroup beforeInputs.
afterInputs object Content to add after all checkbox items within the checkboxes component. See macro options for formGroup afterInputs.
Options for formGroup beforeInputs object
Name Type Description
text string Required. Text to add before all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add before all checkbox items. If html is provided, the text option will be ignored.
Options for formGroup afterInputs object
Name Type Description
text string Required. Text to add after all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add after all checkbox items. If html is provided, the text option will be ignored.
Options for items array objects
Name Type Description
text string Required. 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.
html string Required. 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.
id string Specific id attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
name string Specific name attribute for the checkbox item. If omitted, then component global name string will be applied.
value string Required. The value attribute for the checkbox input.
label object Subset of options for the label used by each checkbox item within the checkboxes component. See macro options for items label.
hint object Can be used to add a hint to each checkbox item within the checkboxes component. See macro options for hint.
divider string Divider text to separate checkbox items, for example the text "or".
checked boolean Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
conditional object Provide additional content to reveal when the checkbox is checked. See macro options for items conditional.
disabled boolean If true, checkbox will be disabled.
classes string Classes to add to the checkbox input tag.
attributes object HTML attributes (for example data attributes) to add to the checkbox input tag.
exclusive boolean 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.
exclusiveGroup string 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.
Options for items label component
Name Type Description
id string The ID of the label tag.
classes string Classes to add to the label tag.
attributes object HTML attributes (for example data attributes) to add to the label tag.
Options for items conditional object
Name Type Description
html string Required. The HTML to reveal when the checkbox is checked. 
{% from "checkboxes/macro.njk" import checkboxes %}

{{ checkboxes({
  idPrefix: "example",
  name: "example",
  fieldset: {
    legend: {
      text: "How do you want to be contacted about this?",
      size: "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 do you want to be contacted about this?".

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 example in a new tab: checkboxes hint text 
<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 do you want to be contacted about this?
      </h1>
    </legend>
    <div class="nhsuk-hint" id="contact-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. Deprecated options are marked as "Deprecated".

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.

Primary options
Name Type Description
id string The ID of the checkboxes component.
describedBy string 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 Can be used to add a fieldset to the checkboxes component. See macro options for fieldset.
hint object Can be used to add a hint to the checkboxes component. See macro options for hint.
errorMessage object 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. See macro options for errorMessage.
formGroup object Additional options for the form group containing the checkboxes component. See macro options for formGroup.
idPrefix string 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 Required. The name attribute for all checkbox items.
items array Required. The checkbox items within the checkboxes component. See macro options for items.
values array 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.
small boolean If set to true, small checkboxes will be used.
classes string Classes to add to the checkboxes container.
attributes object HTML attributes (for example data attributes) to add to the checkboxes container.
Options for formGroup object
Name Type Description
classes string Classes to add to the form group (for example to show error state for the whole group).
attributes object HTML attributes (for example data attributes) to add to the form group.
beforeInputs object Content to add before all checkbox items within the checkboxes component. See macro options for formGroup beforeInputs.
afterInputs object Content to add after all checkbox items within the checkboxes component. See macro options for formGroup afterInputs.
Options for formGroup beforeInputs object
Name Type Description
text string Required. Text to add before all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add before all checkbox items. If html is provided, the text option will be ignored.
Options for formGroup afterInputs object
Name Type Description
text string Required. Text to add after all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add after all checkbox items. If html is provided, the text option will be ignored.
Options for items array objects
Name Type Description
text string Required. 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.
html string Required. 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.
id string Specific id attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
name string Specific name attribute for the checkbox item. If omitted, then component global name string will be applied.
value string Required. The value attribute for the checkbox input.
label object Subset of options for the label used by each checkbox item within the checkboxes component. See macro options for items label.
hint object Can be used to add a hint to each checkbox item within the checkboxes component. See macro options for hint.
divider string Divider text to separate checkbox items, for example the text "or".
checked boolean Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
conditional object Provide additional content to reveal when the checkbox is checked. See macro options for items conditional.
disabled boolean If true, checkbox will be disabled.
classes string Classes to add to the checkbox input tag.
attributes object HTML attributes (for example data attributes) to add to the checkbox input tag.
exclusive boolean 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.
exclusiveGroup string 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.
Options for items label component
Name Type Description
id string The ID of the label tag.
classes string Classes to add to the label tag.
attributes object HTML attributes (for example data attributes) to add to the label tag.
Options for items conditional object
Name Type Description
html string Required. The HTML to reveal when the checkbox is checked. 
{% from "checkboxes/macro.njk" import checkboxes %}

{{ checkboxes({
  idPrefix: "contact",
  name: "contact",
  fieldset: {
    legend: {
      text: "How do you want to be contacted about this?",
      size: "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 example in a new tab: checkboxes items with hints 
<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 medical conditions do you have?
      </h1>
    </legend>
    <div class="nhsuk-hint" id="nationality-hint">
      Select 1 or more
    </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="alzheimers">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="nationality">
          Alzheimer's disease or dementia
        </label>
      </div>
      <div class="nhsuk-checkboxes__item">
        <input class="nhsuk-checkboxes__input" id="nationality-2" name="nationality" type="checkbox" value="asthma">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="nationality-2">
          Asthma
        </label>
      </div>
      <div class="nhsuk-checkboxes__item">
        <input class="nhsuk-checkboxes__input" id="nationality-3" name="nationality" type="checkbox" value="cancer">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="nationality-3">
          Cancer
        </label>
      </div>
      <div class="nhsuk-checkboxes__item">
        <input class="nhsuk-checkboxes__input" id="nationality-4" name="nationality" type="checkbox" value="diabetes" aria-describedby="nationality-4-item-hint">
        <label class="nhsuk-label nhsuk-checkboxes__label" for="nationality-4">
          Diabetes
        </label>
        <div class="nhsuk-hint nhsuk-checkboxes__hint" id="nationality-4-item-hint">
          including type 1, type 2, and gestational diabetes
        </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. Deprecated options are marked as "Deprecated".

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.

Primary options
Name Type Description
id string The ID of the checkboxes component.
describedBy string 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 Can be used to add a fieldset to the checkboxes component. See macro options for fieldset.
hint object Can be used to add a hint to the checkboxes component. See macro options for hint.
errorMessage object 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. See macro options for errorMessage.
formGroup object Additional options for the form group containing the checkboxes component. See macro options for formGroup.
idPrefix string 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 Required. The name attribute for all checkbox items.
items array Required. The checkbox items within the checkboxes component. See macro options for items.
values array 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.
small boolean If set to true, small checkboxes will be used.
classes string Classes to add to the checkboxes container.
attributes object HTML attributes (for example data attributes) to add to the checkboxes container.
Options for formGroup object
Name Type Description
classes string Classes to add to the form group (for example to show error state for the whole group).
attributes object HTML attributes (for example data attributes) to add to the form group.
beforeInputs object Content to add before all checkbox items within the checkboxes component. See macro options for formGroup beforeInputs.
afterInputs object Content to add after all checkbox items within the checkboxes component. See macro options for formGroup afterInputs.
Options for formGroup beforeInputs object
Name Type Description
text string Required. Text to add before all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add before all checkbox items. If html is provided, the text option will be ignored.
Options for formGroup afterInputs object
Name Type Description
text string Required. Text to add after all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add after all checkbox items. If html is provided, the text option will be ignored.
Options for items array objects
Name Type Description
text string Required. 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.
html string Required. 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.
id string Specific id attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
name string Specific name attribute for the checkbox item. If omitted, then component global name string will be applied.
value string Required. The value attribute for the checkbox input.
label object Subset of options for the label used by each checkbox item within the checkboxes component. See macro options for items label.
hint object Can be used to add a hint to each checkbox item within the checkboxes component. See macro options for hint.
divider string Divider text to separate checkbox items, for example the text "or".
checked boolean Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
conditional object Provide additional content to reveal when the checkbox is checked. See macro options for items conditional.
disabled boolean If true, checkbox will be disabled.
classes string Classes to add to the checkbox input tag.
attributes object HTML attributes (for example data attributes) to add to the checkbox input tag.
exclusive boolean 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.
exclusiveGroup string 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.
Options for items label component
Name Type Description
id string The ID of the label tag.
classes string Classes to add to the label tag.
attributes object HTML attributes (for example data attributes) to add to the label tag.
Options for items conditional object
Name Type Description
html string Required. The HTML to reveal when the checkbox is checked. 
{% from "checkboxes/macro.njk" import checkboxes %}

{{ checkboxes({
  idPrefix: "nationality",
  name: "nationality",
  fieldset: {
    legend: {
      text: "What medical conditions do you have?",
      size: "l",
      isPageHeading: true
    }
  },
  hint: {
    text: "Select 1 or more"
  },
  items: [
    {
      value: "alzheimers",
      text: "Alzheimer's disease or dementia"
    },
    {
      value: "asthma",
      text: "Asthma"
    },
    {
      value: "cancer",
      text: "Cancer"
    },
    {
      value: "diabetes",
      text: "Diabetes",
      hint: {
        text: "including type 1, type 2, and gestational diabetes"
      }
    }
  ]
}) }}

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 example in a new tab: checkboxes none option 
<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" 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. Deprecated options are marked as "Deprecated".

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.

Primary options
Name Type Description
id string The ID of the checkboxes component.
describedBy string 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 Can be used to add a fieldset to the checkboxes component. See macro options for fieldset.
hint object Can be used to add a hint to the checkboxes component. See macro options for hint.
errorMessage object 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. See macro options for errorMessage.
formGroup object Additional options for the form group containing the checkboxes component. See macro options for formGroup.
idPrefix string 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 Required. The name attribute for all checkbox items.
items array Required. The checkbox items within the checkboxes component. See macro options for items.
values array 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.
small boolean If set to true, small checkboxes will be used.
classes string Classes to add to the checkboxes container.
attributes object HTML attributes (for example data attributes) to add to the checkboxes container.
Options for formGroup object
Name Type Description
classes string Classes to add to the form group (for example to show error state for the whole group).
attributes object HTML attributes (for example data attributes) to add to the form group.
beforeInputs object Content to add before all checkbox items within the checkboxes component. See macro options for formGroup beforeInputs.
afterInputs object Content to add after all checkbox items within the checkboxes component. See macro options for formGroup afterInputs.
Options for formGroup beforeInputs object
Name Type Description
text string Required. Text to add before all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add before all checkbox items. If html is provided, the text option will be ignored.
Options for formGroup afterInputs object
Name Type Description
text string Required. Text to add after all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add after all checkbox items. If html is provided, the text option will be ignored.
Options for items array objects
Name Type Description
text string Required. 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.
html string Required. 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.
id string Specific id attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
name string Specific name attribute for the checkbox item. If omitted, then component global name string will be applied.
value string Required. The value attribute for the checkbox input.
label object Subset of options for the label used by each checkbox item within the checkboxes component. See macro options for items label.
hint object Can be used to add a hint to each checkbox item within the checkboxes component. See macro options for hint.
divider string Divider text to separate checkbox items, for example the text "or".
checked boolean Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
conditional object Provide additional content to reveal when the checkbox is checked. See macro options for items conditional.
disabled boolean If true, checkbox will be disabled.
classes string Classes to add to the checkbox input tag.
attributes object HTML attributes (for example data attributes) to add to the checkbox input tag.
exclusive boolean 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.
exclusiveGroup string 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.
Options for items label component
Name Type Description
id string The ID of the label tag.
classes string Classes to add to the label tag.
attributes object HTML attributes (for example data attributes) to add to the label tag.
Options for items conditional object
Name Type Description
html string Required. The HTML to reveal when the checkbox is checked. 
{% from "checkboxes/macro.njk" import checkboxes %}

{{ checkboxes({
  idPrefix: "symptoms",
  name: "symptoms",
  fieldset: {
    legend: {
      text: "Do you have any of these symptoms?",
      size: "l",
      isPageHeading: true
    }
  },
  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 example in a new tab: checkboxes conditional 
<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 do you want to be contacted about this?
      </h1>
    </legend>
    <div class="nhsuk-hint" id="contact-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" data-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" data-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" data-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. Deprecated options are marked as "Deprecated".

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.

Primary options
Name Type Description
id string The ID of the checkboxes component.
describedBy string 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 Can be used to add a fieldset to the checkboxes component. See macro options for fieldset.
hint object Can be used to add a hint to the checkboxes component. See macro options for hint.
errorMessage object 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. See macro options for errorMessage.
formGroup object Additional options for the form group containing the checkboxes component. See macro options for formGroup.
idPrefix string 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 Required. The name attribute for all checkbox items.
items array Required. The checkbox items within the checkboxes component. See macro options for items.
values array 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.
small boolean If set to true, small checkboxes will be used.
classes string Classes to add to the checkboxes container.
attributes object HTML attributes (for example data attributes) to add to the checkboxes container.
Options for formGroup object
Name Type Description
classes string Classes to add to the form group (for example to show error state for the whole group).
attributes object HTML attributes (for example data attributes) to add to the form group.
beforeInputs object Content to add before all checkbox items within the checkboxes component. See macro options for formGroup beforeInputs.
afterInputs object Content to add after all checkbox items within the checkboxes component. See macro options for formGroup afterInputs.
Options for formGroup beforeInputs object
Name Type Description
text string Required. Text to add before all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add before all checkbox items. If html is provided, the text option will be ignored.
Options for formGroup afterInputs object
Name Type Description
text string Required. Text to add after all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add after all checkbox items. If html is provided, the text option will be ignored.
Options for items array objects
Name Type Description
text string Required. 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.
html string Required. 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.
id string Specific id attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
name string Specific name attribute for the checkbox item. If omitted, then component global name string will be applied.
value string Required. The value attribute for the checkbox input.
label object Subset of options for the label used by each checkbox item within the checkboxes component. See macro options for items label.
hint object Can be used to add a hint to each checkbox item within the checkboxes component. See macro options for hint.
divider string Divider text to separate checkbox items, for example the text "or".
checked boolean Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
conditional object Provide additional content to reveal when the checkbox is checked. See macro options for items conditional.
disabled boolean If true, checkbox will be disabled.
classes string Classes to add to the checkbox input tag.
attributes object HTML attributes (for example data attributes) to add to the checkbox input tag.
exclusive boolean 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.
exclusiveGroup string 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.
Options for items label component
Name Type Description
id string The ID of the label tag.
classes string Classes to add to the label tag.
attributes object HTML attributes (for example data attributes) to add to the label tag.
Options for items conditional object
Name Type Description
html string Required. The HTML to reveal when the checkbox is checked. 
{% 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 do you want to be contacted about this?",
      size: "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 example in a new tab: checkboxes smaller 
<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. Deprecated options are marked as "Deprecated".

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.

Primary options
Name Type Description
id string The ID of the checkboxes component.
describedBy string 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 Can be used to add a fieldset to the checkboxes component. See macro options for fieldset.
hint object Can be used to add a hint to the checkboxes component. See macro options for hint.
errorMessage object 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. See macro options for errorMessage.
formGroup object Additional options for the form group containing the checkboxes component. See macro options for formGroup.
idPrefix string 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 Required. The name attribute for all checkbox items.
items array Required. The checkbox items within the checkboxes component. See macro options for items.
values array 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.
small boolean If set to true, small checkboxes will be used.
classes string Classes to add to the checkboxes container.
attributes object HTML attributes (for example data attributes) to add to the checkboxes container.
Options for formGroup object
Name Type Description
classes string Classes to add to the form group (for example to show error state for the whole group).
attributes object HTML attributes (for example data attributes) to add to the form group.
beforeInputs object Content to add before all checkbox items within the checkboxes component. See macro options for formGroup beforeInputs.
afterInputs object Content to add after all checkbox items within the checkboxes component. See macro options for formGroup afterInputs.
Options for formGroup beforeInputs object
Name Type Description
text string Required. Text to add before all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add before all checkbox items. If html is provided, the text option will be ignored.
Options for formGroup afterInputs object
Name Type Description
text string Required. Text to add after all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add after all checkbox items. If html is provided, the text option will be ignored.
Options for items array objects
Name Type Description
text string Required. 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.
html string Required. 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.
id string Specific id attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
name string Specific name attribute for the checkbox item. If omitted, then component global name string will be applied.
value string Required. The value attribute for the checkbox input.
label object Subset of options for the label used by each checkbox item within the checkboxes component. See macro options for items label.
hint object Can be used to add a hint to each checkbox item within the checkboxes component. See macro options for hint.
divider string Divider text to separate checkbox items, for example the text "or".
checked boolean Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
conditional object Provide additional content to reveal when the checkbox is checked. See macro options for items conditional.
disabled boolean If true, checkbox will be disabled.
classes string Classes to add to the checkbox input tag.
attributes object HTML attributes (for example data attributes) to add to the checkbox input tag.
exclusive boolean 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.
exclusiveGroup string 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.
Options for items label component
Name Type Description
id string The ID of the label tag.
classes string Classes to add to the label tag.
attributes object HTML attributes (for example data attributes) to add to the label tag.
Options for items conditional object
Name Type Description
html string Required. The HTML to reveal when the checkbox is checked. 
{% from 'checkboxes/macro.njk' import checkboxes %}

{{ checkboxes({
  idPrefix: "example",
  name: "example",
  fieldset: {
    legend: {
      text: "Care setting",
      size: "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

Style error messages like this.

Open this example in a new tab: checkboxes error messages 
<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 do you want to be contacted about this?
      </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 want to be contacted
    </span>
    <div class="nhsuk-checkboxes nhsuk-checkboxes--error" 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. Deprecated options are marked as "Deprecated".

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.

Primary options
Name Type Description
id string The ID of the checkboxes component.
describedBy string 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 Can be used to add a fieldset to the checkboxes component. See macro options for fieldset.
hint object Can be used to add a hint to the checkboxes component. See macro options for hint.
errorMessage object 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. See macro options for errorMessage.
formGroup object Additional options for the form group containing the checkboxes component. See macro options for formGroup.
idPrefix string 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 Required. The name attribute for all checkbox items.
items array Required. The checkbox items within the checkboxes component. See macro options for items.
values array 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.
small boolean If set to true, small checkboxes will be used.
classes string Classes to add to the checkboxes container.
attributes object HTML attributes (for example data attributes) to add to the checkboxes container.
Options for formGroup object
Name Type Description
classes string Classes to add to the form group (for example to show error state for the whole group).
attributes object HTML attributes (for example data attributes) to add to the form group.
beforeInputs object Content to add before all checkbox items within the checkboxes component. See macro options for formGroup beforeInputs.
afterInputs object Content to add after all checkbox items within the checkboxes component. See macro options for formGroup afterInputs.
Options for formGroup beforeInputs object
Name Type Description
text string Required. Text to add before all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add before all checkbox items. If html is provided, the text option will be ignored.
Options for formGroup afterInputs object
Name Type Description
text string Required. Text to add after all checkbox items. If html is provided, the text option will be ignored.
html string Required. HTML to add after all checkbox items. If html is provided, the text option will be ignored.
Options for items array objects
Name Type Description
text string Required. 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.
html string Required. 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.
id string Specific id attribute for the checkbox item. If omitted, then component global idPrefix option will be applied.
name string Specific name attribute for the checkbox item. If omitted, then component global name string will be applied.
value string Required. The value attribute for the checkbox input.
label object Subset of options for the label used by each checkbox item within the checkboxes component. See macro options for items label.
hint object Can be used to add a hint to each checkbox item within the checkboxes component. See macro options for hint.
divider string Divider text to separate checkbox items, for example the text "or".
checked boolean Whether the checkbox should be checked when the page loads. Takes precedence over the top-level values option.
conditional object Provide additional content to reveal when the checkbox is checked. See macro options for items conditional.
disabled boolean If true, checkbox will be disabled.
classes string Classes to add to the checkbox input tag.
attributes object HTML attributes (for example data attributes) to add to the checkbox input tag.
exclusive boolean 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.
exclusiveGroup string 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.
Options for items label component
Name Type Description
id string The ID of the label tag.
classes string Classes to add to the label tag.
attributes object HTML attributes (for example data attributes) to add to the label tag.
Options for items conditional object
Name Type Description
html string Required. The HTML to reveal when the checkbox is checked. 
{% from "checkboxes/macro.njk" import checkboxes %}

{{ checkboxes({
  idPrefix: "contact",
  name: "contact",
  fieldset: {
    legend: {
      text: "How do you want to be contacted about this?",
      size: "l",
      isPageHeading: true
    }
  },
  hint: {
    text: "Select all options that are relevant to you"
  },
  errorMessage: {
    text: "Select how you want 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: November 2025