Form elements - Checkboxes

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

Open this default checkboxes example in a new tab
Copy default checkboxes code 
<form>

  <div class="nhsuk-form-group">

    <fieldset class="nhsuk-fieldset" aria-describedby="example-hint">
      <legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
        <h1 class="nhsuk-fieldset__heading">
          How would you like to be contacted?
        </h1>
      </legend>

      <div class="nhsuk-hint" id="example-hint">
        Select all options that are relevant to you.
      </div>

      <div class="nhsuk-checkboxes">

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="example-1" name="example" type="checkbox" value="email">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="example-1">
            Email
          </label>
        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="example-2" name="example" type="checkbox" value="phone">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="example-2">
            Phone
          </label>
        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="example-3" name="example" type="checkbox" value="text message">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="example-3">
            Text message
          </label>
        </div>

      </div>
    </fieldset>

  </div>

</form>
Close default checkboxes code
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
fieldset object false Options for the fieldset component (for example legend).
hint object false Options for the hint component (for example text).
errorMessage object false Options for the error message component.
idPrefix string false String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
name string true Name attribute for all checkbox items.
items array true Array of checkbox items objects.
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` argument 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` argument 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[].divider string true Optional divider text to separate checkbox items, for example the text "or".
items[].hint object false Provide hint to each checkbox item.
items[].checked boolean false If true, checkbox will be checked.
items[].conditional boolean false If true, content provided will be revealed when the item is checked.
items[].conditional.html string false Provide content for the conditional reveal.
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.
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.
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.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the anchor tag.
Copy default checkboxes code 
{% from 'checkboxes/macro.njk' import checkboxes %}

<form>
  {{ checkboxes({
    idPrefix: "example",
    name: "example",
    fieldset: {
      legend: {
        text: "How would you like to be contacted?",
        classes: "nhsuk-fieldset__legend--l",
        isPageHeading: true
      }
    },
    hint: {
      text: "Select all options that are relevant to you."
    },
    items: [
      {
        value: "email",
        text: "Email"
      },
      {
        value: "phone",
        text: "Phone"
      },
      {
        value: "text message",
        text: "Text message"
      }
    ]
  }) }}
</form>
Close default checkboxes code

When to use checkboxes

Use checkboxes when you need to help users:

  • select more than 1 option from a list
  • toggle a single option on or off

When not to use checkboxes

Do not use the checkboxes component if users can only choose 1 option from a selection. In this case, use a radio.

How to use checkboxes

Group checkboxes together in a <fieldset> with a <legend> that describes them. You can see an example at the top of this page. The legend is usually a question, like "How would you like to be contacted?".

If you're asking just 1 question per page as we recommend, you can set the contents of the <legend> as the page heading. This is good practice as it means screen reader users will only hear the contents once.

Read more on the GOV.UK Design System about making labels and legends headings.

Checkboxes with hint text

Unlike with radios, users can select more than 1 option from a list of checkboxes. Do not assume that users will know how many options they can select.

Use hint text to give users help in context. For example, say "Select all the options that are relevant to you".

Open this hint checkboxes example in a new tab
Copy hint checkboxes code 
<form>

  <div class="nhsuk-form-group">

    <fieldset class="nhsuk-fieldset" aria-describedby="contact-hint">
      <legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
        <h1 class="nhsuk-fieldset__heading">
          How would you like to be contacted?
        </h1>
      </legend>

      <div class="nhsuk-hint" id="contact-hint">
        Select all options that are relevant to you.
      </div>

      <div class="nhsuk-checkboxes">

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="contact" name="contact" type="checkbox" value="email">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="contact">
            Email
          </label>
        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="contact-2" name="contact" type="checkbox" value="phone">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="contact-2">
            Phone
          </label>
        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="contact-3" name="contact" type="checkbox" value="text message">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="contact-3">
            Text message
          </label>
        </div>

      </div>
    </fieldset>

  </div>

</form>
Close hint checkboxes code
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
fieldset object false Options for the fieldset component (for example legend).
hint object false Options for the hint component (for example text).
errorMessage object false Options for the error message component.
idPrefix string false String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
name string true Name attribute for all checkbox items.
items array true Array of checkbox items objects.
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` argument 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` argument 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[].divider string true Optional divider text to separate checkbox items, for example the text "or".
items[].hint object false Provide hint to each checkbox item.
items[].checked boolean false If true, checkbox will be checked.
items[].conditional boolean false If true, content provided will be revealed when the item is checked.
items[].conditional.html string false Provide content for the conditional reveal.
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.
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.
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.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the anchor tag.
Copy hint checkboxes code 
{% from 'checkboxes/macro.njk' import checkboxes %}

<form>
  {{ checkboxes({
    idPrefix: "contact",
    name: "contact",
    fieldset: {
      legend: {
        text: "How would you like to be contacted?",
        classes: "nhsuk-fieldset__legend--l",
        isPageHeading: true
      }
    },
    hint: {
      text: "Select all options that are relevant to you."
    },
    items: [
      {
        value: "email",
        text: "Email",
        id: "contact"
      },
      {
        value: "phone",
        text: "Phone"
      },
      {
        value: "text message",
        text: "Text message"
      }
    ]
  }) }}
</form>
Close hint checkboxes code

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
Copy items with hints checkboxes code 
<form>

  <div class="nhsuk-form-group">

    <fieldset class="nhsuk-fieldset" aria-describedby="nationality-hint">
      <legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
        <h1 class="nhsuk-fieldset__heading">
          What is your nationality?
        </h1>
      </legend>

      <div class="nhsuk-hint" id="nationality-hint">
        If you have dual nationality, select all options that are relevant to you.
      </div>

      <div class="nhsuk-checkboxes">

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="nationality-1" name="nationality" type="checkbox" value="british" aria-describedby="nationality-1-item-hint">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="nationality-1">
            British
          </label>
          <div class="nhsuk-hint nhsuk-checkboxes__hint" id="nationality-1-item-hint">
            including English, Scottish, Welsh and Northern Irish
          </div>
        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="nationality-2" name="nationality" type="checkbox" value="irish">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="nationality-2">
            Irish
          </label>
        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="nationality-3" name="nationality" type="checkbox" value="other">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="nationality-3">
            Citizen of another country
          </label>
        </div>

      </div>
    </fieldset>

  </div>

</form>
Close items with hints checkboxes code
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
fieldset object false Options for the fieldset component (for example legend).
hint object false Options for the hint component (for example text).
errorMessage object false Options for the error message component.
idPrefix string false String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
name string true Name attribute for all checkbox items.
items array true Array of checkbox items objects.
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` argument 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` argument 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[].divider string true Optional divider text to separate checkbox items, for example the text "or".
items[].hint object false Provide hint to each checkbox item.
items[].checked boolean false If true, checkbox will be checked.
items[].conditional boolean false If true, content provided will be revealed when the item is checked.
items[].conditional.html string false Provide content for the conditional reveal.
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.
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.
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.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the anchor tag.
Copy items with hints checkboxes code 
{% from 'checkboxes/macro.njk' import checkboxes %}

<form>
  {{ checkboxes({
    idPrefix: "nationality",
    name: "nationality",
    fieldset: {
      legend: {
        text: "What is your nationality?",
        isPageHeading: true,
        classes: "nhsuk-fieldset__legend--l"
      }
    },
    hint: {
      text: "If you have dual nationality, select all options that are relevant to you."
    },
    items: [
      {
        value: "british",
        text: "British",
        hint: {
          text: "including English, Scottish, Welsh and Northern Irish"
        }
      },
      {
        value: "irish",
        text: "Irish"
      },
      {
        value: "other",
        text: "Citizen of another country"
      }
    ]
  }) }}
</form>
Close items with hints checkboxes code

Conditionally revealing content

You can add conditionally revealing content to checkboxes, so users only see content when it's relevant to them.

For example, you could reveal a phone number input only when a user chooses to be contacted by phone.

Open this conditional checkboxes example in a new tab
Copy conditional checkboxes code 
<form>

  <div class="nhsuk-form-group">

    <fieldset class="nhsuk-fieldset" aria-describedby="contact-hint">
      <legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
        <h1 class="nhsuk-fieldset__heading">
          How would you prefer to be contacted?
        </h1>
      </legend>

      <div class="nhsuk-hint" id="contact-hint">
        Select all options that are relevant to you.
      </div>

      <div class="nhsuk-checkboxes nhsuk-checkboxes--conditional">

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="contact-1" name="contact" type="checkbox" value="email" aria-controls="conditional-contact-1" aria-expanded="false">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="contact-1">
            Email
          </label>
        </div>

        <div class="nhsuk-checkboxes__conditional nhsuk-checkboxes__conditional--hidden" id="conditional-contact-1">

          <div class="nhsuk-form-group">
            <label class="nhsuk-label" for="email">
              Email address
            </label>
            <input class="nhsuk-input nhsuk-u-width-two-thirds" id="email" name="email" type="text">
          </div>

        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="contact-2" name="contact" type="checkbox" value="phone" aria-controls="conditional-contact-2" aria-expanded="false">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="contact-2">
            Phone
          </label>
        </div>

        <div class="nhsuk-checkboxes__conditional nhsuk-checkboxes__conditional--hidden" id="conditional-contact-2">

          <div class="nhsuk-form-group">
            <label class="nhsuk-label" for="phone">
              Phone number
            </label>
            <input class="nhsuk-input nhsuk-u-width-two-thirds" id="phone" name="phone" type="text">
          </div>

        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="contact-3" name="contact" type="checkbox" value="text" aria-controls="conditional-contact-3" aria-expanded="false">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="contact-3">
            Text message
          </label>
        </div>

        <div class="nhsuk-checkboxes__conditional nhsuk-checkboxes__conditional--hidden" id="conditional-contact-3">

          <div class="nhsuk-form-group">
            <label class="nhsuk-label" for="mobile">
              Mobile phone number
            </label>
            <input class="nhsuk-input nhsuk-u-width-two-thirds" id="mobile" name="mobile" type="text">
          </div>

        </div>

      </div>
    </fieldset>

  </div>

</form>
Close conditional checkboxes code
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
fieldset object false Options for the fieldset component (for example legend).
hint object false Options for the hint component (for example text).
errorMessage object false Options for the error message component.
idPrefix string false String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
name string true Name attribute for all checkbox items.
items array true Array of checkbox items objects.
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` argument 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` argument 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[].divider string true Optional divider text to separate checkbox items, for example the text "or".
items[].hint object false Provide hint to each checkbox item.
items[].checked boolean false If true, checkbox will be checked.
items[].conditional boolean false If true, content provided will be revealed when the item is checked.
items[].conditional.html string false Provide content for the conditional reveal.
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.
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.
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.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the anchor tag.
Copy conditional checkboxes code 
{% from 'checkboxes/macro.njk' import checkboxes %}
{% from 'input/macro.njk' import input %}

{% set emailHtml %}
  {{ input({
    id: "email",
    name: "email",
    classes: "nhsuk-u-width-two-thirds",
    label: {
      text: "Email address"
    }
  }) }}
{% endset -%}

{% set phoneHtml %}
  {{ input({
    id: "phone",
    name: "phone",
    classes: "nhsuk-u-width-two-thirds",
    label: {
      text: "Phone number"
    }
  }) }}
{% endset -%}

{% set mobileHtml %}
  {{ input({
    id: "mobile",
    name: "mobile",
    classes: "nhsuk-u-width-two-thirds",
    label: {
      text: "Mobile phone number"
    }
  }) }}
{% endset -%}

<form>
  {{ checkboxes({
    idPrefix: "contact",
    name: "contact",
    fieldset: {
      legend: {
        text: "How would you prefer to be contacted?",
        classes: "nhsuk-fieldset__legend--l",
        isPageHeading: "true"
      }
    },
    hint: {
      text: "Select all options that are relevant to you."
    },
    items: [
      {
        value: "email",
        text: "Email",
        "conditional": {
          "html": emailHtml
        }
      },
      {
        "value": "phone",
        "text": "Phone",
        "conditional": {
          "html": phoneHtml
        }
      },
      {
        "value": "text",
        "text": "Text message",
        "conditional": {
          "html": mobileHtml
        }
      }
    ]
  }) }}
</form>
Close conditional checkboxes code

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

Adding an option for "none"

You can give users the option to say none of the other options apply to them.

This option means users need to actively select "none" rather than leave all the boxes unchecked, which makes sure they do not skip the question by accident.

Remember to start by asking 1 question per page. You might be able to remove the need for a "none" option by asking the user a better question or by using filter questions to filter users out beforehand.

Show the "none" option last. Separate it from the other options using a divider, normally the word "or".

Write a label that repeats the key part of the question. For example, for the question "Do you have any of these symptoms?", say "No, I do not have any of these symptoms". Avoid phrases like "none of the above" because this is a visual reference and might be hard for people who use screen readers to understand.

To enable some JavaScript that unchecks all other checkboxes when the user clicks "none", add the data-checkbox-exclusive behaviour to the "none" checkbox.

Open this none option checkboxes example in a new tab
Copy none option checkboxes code 
<form>

  <div class="nhsuk-form-group">

    <fieldset class="nhsuk-fieldset" aria-describedby="symptoms-hint">
      <legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
        <h1 class="nhsuk-fieldset__heading">
          Do you have any of these symptoms?
        </h1>
      </legend>

      <div class="nhsuk-hint" id="symptoms-hint">
        Select all the symptoms you have.
      </div>

      <div class="nhsuk-checkboxes">

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="symptoms-1" name="symptoms" type="checkbox" value="sorethroat" data-checkbox-exclusive-group="symptoms-list">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="symptoms-1">
            Sore throat
          </label>
        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="symptoms-2" name="symptoms" type="checkbox" value="runnynose" data-checkbox-exclusive-group="symptoms-list">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="symptoms-2">
            Runny nose
          </label>
        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="symptoms-3" name="symptoms" type="checkbox" value="muscleorjointpain" data-checkbox-exclusive-group="symptoms-list">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="symptoms-3">
            Muscle or joint pain
          </label>
        </div>

        <div class="nhsuk-checkboxes__divider">or</div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="symptoms-5" name="symptoms" type="checkbox" value="none" data-checkbox-exclusive data-checkbox-exclusive-group="symptoms-list">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="symptoms-5">
            No, I do not have any of these symptoms
          </label>
        </div>

      </div>
    </fieldset>

  </div>

</form>
Close none option checkboxes code
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
fieldset object false Options for the fieldset component (for example legend).
hint object false Options for the hint component (for example text).
errorMessage object false Options for the error message component.
idPrefix string false String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
name string true Name attribute for all checkbox items.
items array true Array of checkbox items objects.
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` argument 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` argument 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[].divider string true Optional divider text to separate checkbox items, for example the text "or".
items[].hint object false Provide hint to each checkbox item.
items[].checked boolean false If true, checkbox will be checked.
items[].conditional boolean false If true, content provided will be revealed when the item is checked.
items[].conditional.html string false Provide content for the conditional reveal.
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.
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.
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.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the anchor tag.
Copy none option checkboxes code 
{% from 'checkboxes/macro.njk' import checkboxes %}

<form>
  {{ checkboxes({
    idPrefix: "symptoms",
    name: "symptoms",
    fieldset: {
      legend: {
        text: "Do you have any of these symptoms?",
        isPageHeading: true,
        classes: "nhsuk-fieldset__legend--l"
      }
    },
    hint: {
      text: "Select all the symptoms you have."
    },
    items: [
      {
        value: "sorethroat",
        text: "Sore throat",
        exclusiveGroup: "symptoms-list"
      },
      {
        value: "runnynose",
        text: "Runny nose",
        exclusiveGroup: "symptoms-list"
      },
      {
        value: "muscleorjointpain",
        text: "Muscle or joint pain",
        exclusiveGroup: "symptoms-list"
      },
      {
        divider: "or"
      },
      {
        value: "none",
        text: "No, I do not have any of these symptoms",
        exclusive: true,
        exclusiveGroup: "symptoms-list"
      }
    ]
  }) }}
</form>
Close none option checkboxes code

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

Error messages

Error messages should be styled like this:

Open this error messages checkboxes example in a new tab
Copy error messages checkboxes code 
<form>

  <div class="nhsuk-form-group nhsuk-form-group--error">

    <fieldset class="nhsuk-fieldset" aria-describedby="contact-hint contact-error">
      <legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--l">
        <h1 class="nhsuk-fieldset__heading">
          How would you like to be contacted?
        </h1>
      </legend>

      <div class="nhsuk-hint" id="contact-hint">
        Select all options that are relevant to you.
      </div>

      <span class="nhsuk-error-message" id="contact-error">
        <span class="nhsuk-u-visually-hidden">Error:</span> Select how you like to be contacted
      </span>

      <div class="nhsuk-checkboxes">

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="contact" name="contact" type="checkbox" value="email">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="contact">
            Email
          </label>
        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="contact-2" name="contact" type="checkbox" value="phone">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="contact-2">
            Phone
          </label>
        </div>

        <div class="nhsuk-checkboxes__item">
          <input class="nhsuk-checkboxes__input" id="contact-3" name="contact" type="checkbox" value="text message">
          <label class="nhsuk-label nhsuk-checkboxes__label" for="contact-3">
            Text message
          </label>
        </div>

      </div>
    </fieldset>

  </div>

</form>
Close error messages checkboxes code
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
fieldset object false Options for the fieldset component (for example legend).
hint object false Options for the hint component (for example text).
errorMessage object false Options for the error message component.
idPrefix string false String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
name string true Name attribute for all checkbox items.
items array true Array of checkbox items objects.
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` argument 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` argument 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[].divider string true Optional divider text to separate checkbox items, for example the text "or".
items[].hint object false Provide hint to each checkbox item.
items[].checked boolean false If true, checkbox will be checked.
items[].conditional boolean false If true, content provided will be revealed when the item is checked.
items[].conditional.html string false Provide content for the conditional reveal.
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.
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.
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.
classes string false Classes to add to the checkboxes container.
attributes object false HTML attributes (for example data attributes) to add to the anchor tag.
Copy error messages checkboxes code 
{% from 'checkboxes/macro.njk' import checkboxes %}

<form>
  {{ checkboxes({
    idPrefix: "contact",
    name: "contact",
    fieldset: {
      legend: {
        text: "How would you like to be contacted?",
        classes: "nhsuk-fieldset__legend--l",
        isPageHeading: true
      }
    },
    hint: {
      text: "Select all options that are relevant to you."
    },
    errorMessage: {
      text: "Select how you like to be contacted"
    },
    items: [
      {
        value: "email",
        text: "Email",
        id: "contact"
      },
      {
        value: "phone",
        text: "Phone"
      },
      {
        value: "text message",
        text: "Text message"
      }
    ]
  }) }}
</form>
Close error messages checkboxes code

Follow:

Research

Our checkboxes are based on the GOV.UK Design System. Read more about how GOV.UK developed and tested them.

Help us improve this guidance

Share insights or feedback and take part in the discussion. We use GitHub as a collaboration space. All the information on it is open to the public.

Feedback or share insights on GitHub

Read more about how to feedback or share insights.

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

Updated: January 2022