Form elements - Checkboxes

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

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

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

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

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

      <div class="hs2-checkboxes">

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

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

        <div class="hs2-checkboxes__item">
          <input class="hs2-checkboxes__input" id="example-3" name="example" type="checkbox" value="text message">
          <label class="hs2-label hs2-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
Name fieldset Type object Required false Description Options for the fieldset component (for example legend).
Name hint Type object Required false Description Options for the hint component (for example text).
Name errorMessage Type object Required false Description Options for the error message component.
Name idPrefix Type string Required false Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
Name name Type string Required true Description Name attribute for all checkbox items.
Name items Type array Required true Description Array of checkbox items objects.
Name items[].text Type string Required true Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].html Type string Required true Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].id Type string Required false Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied.
Name items[].name Type string Required false Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied.
Name items[].value Type string Required true Description Value for the checkbox input.
Name items[].divider Type string Required true Description Optional divider text to separate checkbox items, for example the text "or".
Name items[].hint Type object Required false Description Provide hint to each checkbox item.
Name items[].checked Type boolean Required false Description If true, checkbox will be checked.
Name items[].conditional Type boolean Required false Description If true, content provided will be revealed when the item is checked.
Name items[].conditional.html Type string Required false Description Provide content for the conditional reveal.
Name items[].disabled Type boolean Required false Description If true, checkbox will be disabled.
Name items[].attributes Type object Required false Description HTML attributes (for example data attributes) to add to the checkbox input tag.
Name exclusive Type boolean Required false Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked.
Name exclusiveGroup Type string Required false Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario.
Name classes Type string Required false Description Classes to add to the checkboxes container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the anchor tag.
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": "hs2-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?".

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 new window
Copy hint checkboxes code 
<form>

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

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

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

      <div class="hs2-checkboxes">

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

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

        <div class="hs2-checkboxes__item">
          <input class="hs2-checkboxes__input" id="contact-3" name="contact" type="checkbox" value="text message">
          <label class="hs2-label hs2-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
Name fieldset Type object Required false Description Options for the fieldset component (for example legend).
Name hint Type object Required false Description Options for the hint component (for example text).
Name errorMessage Type object Required false Description Options for the error message component.
Name idPrefix Type string Required false Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
Name name Type string Required true Description Name attribute for all checkbox items.
Name items Type array Required true Description Array of checkbox items objects.
Name items[].text Type string Required true Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].html Type string Required true Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].id Type string Required false Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied.
Name items[].name Type string Required false Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied.
Name items[].value Type string Required true Description Value for the checkbox input.
Name items[].divider Type string Required true Description Optional divider text to separate checkbox items, for example the text "or".
Name items[].hint Type object Required false Description Provide hint to each checkbox item.
Name items[].checked Type boolean Required false Description If true, checkbox will be checked.
Name items[].conditional Type boolean Required false Description If true, content provided will be revealed when the item is checked.
Name items[].conditional.html Type string Required false Description Provide content for the conditional reveal.
Name items[].disabled Type boolean Required false Description If true, checkbox will be disabled.
Name items[].attributes Type object Required false Description HTML attributes (for example data attributes) to add to the checkbox input tag.
Name exclusive Type boolean Required false Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked.
Name exclusiveGroup Type string Required false Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario.
Name classes Type string Required false Description Classes to add to the checkboxes container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the anchor tag.
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": "hs2-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 new window
Copy items with hints checkboxes code 
<form>

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

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

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

      <div class="hs2-checkboxes">

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

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

        <div class="hs2-checkboxes__item">
          <input class="hs2-checkboxes__input" id="nationality-3" name="nationality" type="checkbox" value="other">
          <label class="hs2-label hs2-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
Name fieldset Type object Required false Description Options for the fieldset component (for example legend).
Name hint Type object Required false Description Options for the hint component (for example text).
Name errorMessage Type object Required false Description Options for the error message component.
Name idPrefix Type string Required false Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
Name name Type string Required true Description Name attribute for all checkbox items.
Name items Type array Required true Description Array of checkbox items objects.
Name items[].text Type string Required true Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].html Type string Required true Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].id Type string Required false Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied.
Name items[].name Type string Required false Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied.
Name items[].value Type string Required true Description Value for the checkbox input.
Name items[].divider Type string Required true Description Optional divider text to separate checkbox items, for example the text "or".
Name items[].hint Type object Required false Description Provide hint to each checkbox item.
Name items[].checked Type boolean Required false Description If true, checkbox will be checked.
Name items[].conditional Type boolean Required false Description If true, content provided will be revealed when the item is checked.
Name items[].conditional.html Type string Required false Description Provide content for the conditional reveal.
Name items[].disabled Type boolean Required false Description If true, checkbox will be disabled.
Name items[].attributes Type object Required false Description HTML attributes (for example data attributes) to add to the checkbox input tag.
Name exclusive Type boolean Required false Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked.
Name exclusiveGroup Type string Required false Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario.
Name classes Type string Required false Description Classes to add to the checkboxes container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the anchor tag.
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: "hs2-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 new window
Copy conditional checkboxes code 
<form>

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

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

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

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

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

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

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

        </div>

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

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

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

        </div>

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

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

          <div class="hs2-form-group">
            <label class="hs2-label" for="mobile">
              Mobile phone number
            </label>
            <input class="hs2-input hs2-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
Name fieldset Type object Required false Description Options for the fieldset component (for example legend).
Name hint Type object Required false Description Options for the hint component (for example text).
Name errorMessage Type object Required false Description Options for the error message component.
Name idPrefix Type string Required false Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
Name name Type string Required true Description Name attribute for all checkbox items.
Name items Type array Required true Description Array of checkbox items objects.
Name items[].text Type string Required true Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].html Type string Required true Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].id Type string Required false Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied.
Name items[].name Type string Required false Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied.
Name items[].value Type string Required true Description Value for the checkbox input.
Name items[].divider Type string Required true Description Optional divider text to separate checkbox items, for example the text "or".
Name items[].hint Type object Required false Description Provide hint to each checkbox item.
Name items[].checked Type boolean Required false Description If true, checkbox will be checked.
Name items[].conditional Type boolean Required false Description If true, content provided will be revealed when the item is checked.
Name items[].conditional.html Type string Required false Description Provide content for the conditional reveal.
Name items[].disabled Type boolean Required false Description If true, checkbox will be disabled.
Name items[].attributes Type object Required false Description HTML attributes (for example data attributes) to add to the checkbox input tag.
Name exclusive Type boolean Required false Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked.
Name exclusiveGroup Type string Required false Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario.
Name classes Type string Required false Description Classes to add to the checkboxes container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the anchor tag.
Copy conditional checkboxes code 
{% from 'checkboxes/macro.njk' import checkboxes %}
{% from 'input/macro.njk' import input %}

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

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

{% set mobileHtml %}
  {{ input({
    id: "mobile",
    name: "mobile",
    classes: "hs2-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": "hs2-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 new window
Copy none option checkboxes code 
<form>

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

    <fieldset class="hs2-fieldset" aria-describedby="non-options-hint">
      <legend class="hs2-fieldset__legend hs2-fieldset__legend--l">
        <h1 class="hs2-fieldset__heading">
          Example for none option checkbox
        </h1>
      </legend>

      <div class="hs2-hint" id="non-options-hint">
        Select all the options you have.
      </div>

      <div class="hs2-checkboxes">

        <div class="hs2-checkboxes__item">
          <input class="hs2-checkboxes__input" id="non-options-1" name="non-options" type="checkbox" value="option1" data-checkbox-exclusive-group="non-options-list">
          <label class="hs2-label hs2-checkboxes__label" for="non-options-1">
            Option one
          </label>
        </div>

        <div class="hs2-checkboxes__item">
          <input class="hs2-checkboxes__input" id="non-options-2" name="non-options" type="checkbox" value="option2" data-checkbox-exclusive-group="non-options-list">
          <label class="hs2-label hs2-checkboxes__label" for="non-options-2">
            Option two
          </label>
        </div>

        <div class="hs2-checkboxes__item">
          <input class="hs2-checkboxes__input" id="non-options-3" name="non-options" type="checkbox" value="option3" data-checkbox-exclusive-group="non-options-list">
          <label class="hs2-label hs2-checkboxes__label" for="non-options-3">
            Option three
          </label>
        </div>

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

        <div class="hs2-checkboxes__item">
          <input class="hs2-checkboxes__input" id="non-options-5" name="non-options" type="checkbox" value="none" data-checkbox-exclusive data-checkbox-exclusive-group="non-options-list">
          <label class="hs2-label hs2-checkboxes__label" for="non-options-5">
            No, I do not have any of these options
          </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
Name fieldset Type object Required false Description Options for the fieldset component (for example legend).
Name hint Type object Required false Description Options for the hint component (for example text).
Name errorMessage Type object Required false Description Options for the error message component.
Name idPrefix Type string Required false Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
Name name Type string Required true Description Name attribute for all checkbox items.
Name items Type array Required true Description Array of checkbox items objects.
Name items[].text Type string Required true Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].html Type string Required true Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].id Type string Required false Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied.
Name items[].name Type string Required false Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied.
Name items[].value Type string Required true Description Value for the checkbox input.
Name items[].divider Type string Required true Description Optional divider text to separate checkbox items, for example the text "or".
Name items[].hint Type object Required false Description Provide hint to each checkbox item.
Name items[].checked Type boolean Required false Description If true, checkbox will be checked.
Name items[].conditional Type boolean Required false Description If true, content provided will be revealed when the item is checked.
Name items[].conditional.html Type string Required false Description Provide content for the conditional reveal.
Name items[].disabled Type boolean Required false Description If true, checkbox will be disabled.
Name items[].attributes Type object Required false Description HTML attributes (for example data attributes) to add to the checkbox input tag.
Name exclusive Type boolean Required false Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked.
Name exclusiveGroup Type string Required false Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario.
Name classes Type string Required false Description Classes to add to the checkboxes container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the anchor tag.
Copy none option checkboxes code 
{% from 'checkboxes/macro.njk' import checkboxes %}

<form>
  {{ checkboxes({
    idPrefix: "non-options",
    name: "non-options",
    fieldset: {
      legend: {
        text: "Example for none option checkbox",
        isPageHeading: true,
        classes: "hs2-fieldset__legend--l"
      }
    },
    hint: {
      text: "Select all the options you have."
    },
    items: [
      {
        value: "option1",
        text: "Option one",
        exclusiveGroup: "non-options-list"
      },
      {
        value: "option2",
        text: "Option two",
        exclusiveGroup: "non-options-list"
      },
      {
        value: "option3",
        text: "Option three",
        exclusiveGroup: "non-options-list"
      },
      {
        divider: "or"
      },
      {
        value: "none",
        text: "No, I do not have any of these options",
        exclusive: true,
        exclusiveGroup: "non-options-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 new window
Copy error messages checkboxes code 
<form>

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

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

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

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

      <div class="hs2-checkboxes">

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

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

        <div class="hs2-checkboxes__item">
          <input class="hs2-checkboxes__input" id="contact-3" name="contact" type="checkbox" value="text message">
          <label class="hs2-label hs2-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
Name fieldset Type object Required false Description Options for the fieldset component (for example legend).
Name hint Type object Required false Description Options for the hint component (for example text).
Name errorMessage Type object Required false Description Options for the error message component.
Name idPrefix Type string Required false Description String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
Name name Type string Required true Description Name attribute for all checkbox items.
Name items Type array Required true Description Array of checkbox items objects.
Name items[].text Type string Required true Description If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].html Type string Required true Description If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
Name items[].id Type string Required false Description Specific id attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied.
Name items[].name Type string Required false Description Specific name for the checkbox item. If omitted, then component global `name` string will be applied.
Name items[].value Type string Required true Description Value for the checkbox input.
Name items[].divider Type string Required true Description Optional divider text to separate checkbox items, for example the text "or".
Name items[].hint Type object Required false Description Provide hint to each checkbox item.
Name items[].checked Type boolean Required false Description If true, checkbox will be checked.
Name items[].conditional Type boolean Required false Description If true, content provided will be revealed when the item is checked.
Name items[].conditional.html Type string Required false Description Provide content for the conditional reveal.
Name items[].disabled Type boolean Required false Description If true, checkbox will be disabled.
Name items[].attributes Type object Required false Description HTML attributes (for example data attributes) to add to the checkbox input tag.
Name exclusive Type boolean Required false Description If set to `true`, marks this checkbox as the None option in a None of these type behaviour. Unchecking all other checkboxes in the group when None is clicked.
Name exclusiveGroup Type string Required false Description Used in conjunction with `exclusive` - this should be set to a string which groups checkboxes together into a set for use in a None of these scenario.
Name classes Type string Required false Description Classes to add to the checkboxes container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the anchor tag.
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": "hs2-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.