Components

Checkboxes

Let users select one or more options by using the checkboxes component.

Open this checkboxes example in a new tab

Who did you report the incident to?

Select all that apply.
HTML 
<div class="govuk-form-group">
  <fieldset class="govuk-fieldset" aria-describedby="incident-default-hint">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
      <h1 class="govuk-fieldset__heading">
        Who did you report the incident to?
      </h1>
    </legend>
    <div id="incident-default-hint" class="govuk-hint">
      Select all that apply.
    </div>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-default"
          name="incident-default"
          type="checkbox"
          value="unit-medic"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-default"
        >
          Unit medic
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-default-2"
          name="incident-default"
          type="checkbox"
          value="hospital"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-default-2"
        >
          Hospital
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-default-3"
          name="incident-default"
          type="checkbox"
          value="chain-of-command"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-default-3"
        >
          Chain of command
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-default-4"
          name="incident-default"
          type="checkbox"
          value="colleague"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-default-4"
        >
          Colleague
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-default-5"
          name="incident-default"
          type="checkbox"
          value="other-person"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-default-5"
        >
          Other person
        </label>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks
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.

Primary options
Name Type Description
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 fieldset.
hint object

Can be used to add a hint to the checkboxes component.

See 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 error message.
formGroup object

Additional options for the form group containing the checkboxes component.

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

Name attribute for all checkbox items.
items array Required.

The checkbox items within the checkboxes component.

See 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.
classes string

Classes to add to the checkboxes container.
attributes object

HTML attributes (for example data attributes) to add to the anchor tag.
Options for formGroup
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 beforeInputs.
afterInputs object

Content to add after all checkbox items within the checkboxes component.

See afterInputs.
Options for afterInputs
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 beforeInputs
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 hint
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the hint. 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 the hint. If html is provided, the text option will be ignored.
id string

Optional ID attribute to add to the hint span tag.
classes string

Classes to add to the hint span tag.
attributes object

HTML attributes (for example data attributes) to add to the hint span tag.
Options for items
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 for the checkbox item. If omitted, then component global name string will be applied.
value string Required.

Value for the checkbox input.
label object

Subset of options for the label used by each checkbox item within the checkboxes component.

See label. See label.
hint object

Can be used to add a hint to each checkbox item within the checkboxes component.

See 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 conditional.
behaviour string

If set to "exclusive", implements a 'None of these' type behaviour via JavaScript when checkboxes are clicked.
disabled boolean

If true, checkbox will be disabled.
attributes object

HTML attributes (for example data attributes) to add to the checkbox input tag.
Options for conditional
Name Type Description
html string Required.

The HTML to reveal when the checkbox is checked.
Options for label
Name Type Description
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 label
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the 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 the label. If html is provided, the text option will be ignored.
for string

The value of the for attribute, the ID of the input the label is associated with.
isPageHeading boolean

Whether the label also acts as the heading for the page.
classes string

Classes to add to the label tag.
attributes object

HTML attributes (for example data attributes) to add to the label tag.

 
{% from "moduk/components/checkboxes/macro.njk" import modukCheckboxes -%}

{{ modukCheckboxes({
  name: "incident-default",
  fieldset: {
    legend: {
      text: "Who did you report the incident to?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--l"
    }
  },
  hint: {
    text: "Select all that apply."
  },
  items: [
    {
      value: "unit-medic",
      text: "Unit medic"
    },
    {
      value: "hospital",
      text: "Hospital"
    },
    {
      value: "chain-of-command",
      text: "Chain of command"
    },
    {
      value: "colleague",
      text: "Colleague"
    },
    {
      value: "other-person",
      text: "Other person"
    }
  ]
}) -}}

See GOV.UK checkboxes component guidance for:

  • when to use this component
  • when not to use it

How it works

See GOV.UK checkboxes component guidance for detail on how this component works.

If you’re asking one question on the page

If you’re asking just one question per page as recommended, you can set the contents of the <legend> as the page heading. This is good practice as it means that users of screen readers will only hear the contents once.

Open this checkboxes example in a new tab

Who did you report the incident to?

Select all that apply.
HTML 
<div class="govuk-form-group">
  <fieldset
    class="govuk-fieldset"
    aria-describedby="technologies-with-page-heading-hint"
  >
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
      <h1 class="govuk-fieldset__heading">
        Who did you report the incident to?
      </h1>
    </legend>
    <div id="technologies-with-page-heading-hint" class="govuk-hint">
      Select all that apply.
    </div>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="technologies-with-page-heading"
          name="technologies-with-page-heading"
          type="checkbox"
          value="unit-medic"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="technologies-with-page-heading"
        >
          Unit medic
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="technologies-with-page-heading-2"
          name="technologies-with-page-heading"
          type="checkbox"
          value="hospital"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="technologies-with-page-heading-2"
        >
          Hospital
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="technologies-with-page-heading-3"
          name="technologies-with-page-heading"
          type="checkbox"
          value="chain-of-command"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="technologies-with-page-heading-3"
        >
          Chain of command
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="technologies-with-page-heading-4"
          name="technologies-with-page-heading"
          type="checkbox"
          value="colleague"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="technologies-with-page-heading-4"
        >
          Colleague
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="technologies-with-page-heading-5"
          name="technologies-with-page-heading"
          type="checkbox"
          value="other-person"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="technologies-with-page-heading-5"
        >
          Other person
        </label>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks
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.

Primary options
Name Type Description
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 fieldset.
hint object

Can be used to add a hint to the checkboxes component.

See 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 error message.
formGroup object

Additional options for the form group containing the checkboxes component.

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

Name attribute for all checkbox items.
items array Required.

The checkbox items within the checkboxes component.

See 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.
classes string

Classes to add to the checkboxes container.
attributes object

HTML attributes (for example data attributes) to add to the anchor tag.
Options for formGroup
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 beforeInputs.
afterInputs object

Content to add after all checkbox items within the checkboxes component.

See afterInputs.
Options for afterInputs
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 beforeInputs
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 hint
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the hint. 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 the hint. If html is provided, the text option will be ignored.
id string

Optional ID attribute to add to the hint span tag.
classes string

Classes to add to the hint span tag.
attributes object

HTML attributes (for example data attributes) to add to the hint span tag.
Options for items
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 for the checkbox item. If omitted, then component global name string will be applied.
value string Required.

Value for the checkbox input.
label object

Subset of options for the label used by each checkbox item within the checkboxes component.

See label. See label.
hint object

Can be used to add a hint to each checkbox item within the checkboxes component.

See 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 conditional.
behaviour string

If set to "exclusive", implements a 'None of these' type behaviour via JavaScript when checkboxes are clicked.
disabled boolean

If true, checkbox will be disabled.
attributes object

HTML attributes (for example data attributes) to add to the checkbox input tag.
Options for conditional
Name Type Description
html string Required.

The HTML to reveal when the checkbox is checked.
Options for label
Name Type Description
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 label
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the 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 the label. If html is provided, the text option will be ignored.
for string

The value of the for attribute, the ID of the input the label is associated with.
isPageHeading boolean

Whether the label also acts as the heading for the page.
classes string

Classes to add to the label tag.
attributes object

HTML attributes (for example data attributes) to add to the label tag.

 
{% from "moduk/components/checkboxes/macro.njk" import modukCheckboxes -%}

{{ modukCheckboxes({
  name: "technologies-with-page-heading",
  fieldset: {
    legend: {
      text: "Who did you report the incident to?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--l"
    }
  },
  hint: {
    text: "Select all that apply."
  },
  items: [
    {
      value: "unit-medic",
      text: "Unit medic"
    },
    {
      value: "hospital",
      text: "Hospital"
    },
    {
      value: "chain-of-command",
      text: "Chain of command"
    },
    {
      value: "colleague",
      text: "Colleague"
    },
    {
      value: "other-person",
      text: "Other person"
    }
  ]
}) -}}

If you’re asking more than one question on the page

If you’re asking more than one question on the page, do not set the contents of the <legend> as the page heading.

Open this checkboxes example in a new tab
Who did you report the incident to?
Select all that apply.
HTML 
<div class="govuk-form-group">
  <fieldset
    class="govuk-fieldset"
    aria-describedby="incident-not-as-page-heading-hint"
  >
    <legend class="govuk-fieldset__legend">
      Who did you report the incident to?
    </legend>
    <div id="incident-not-as-page-heading-hint" class="govuk-hint">
      Select all that apply.
    </div>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-not-as-page-heading"
          name="incident-not-as-page-heading"
          type="checkbox"
          value="unit-medic"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-not-as-page-heading"
        >
          Unit medic
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-not-as-page-heading-2"
          name="incident-not-as-page-heading"
          type="checkbox"
          value="hospital"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-not-as-page-heading-2"
        >
          Hospital
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-not-as-page-heading-3"
          name="incident-not-as-page-heading"
          type="checkbox"
          value="chain-of-command"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-not-as-page-heading-3"
        >
          Chain of command
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-not-as-page-heading-4"
          name="incident-not-as-page-heading"
          type="checkbox"
          value="colleague"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-not-as-page-heading-4"
        >
          Colleague
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-not-as-page-heading-5"
          name="incident-not-as-page-heading"
          type="checkbox"
          value="other-person"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-not-as-page-heading-5"
        >
          Other person
        </label>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks
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.

Primary options
Name Type Description
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 fieldset.
hint object

Can be used to add a hint to the checkboxes component.

See 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 error message.
formGroup object

Additional options for the form group containing the checkboxes component.

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

Name attribute for all checkbox items.
items array Required.

The checkbox items within the checkboxes component.

See 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.
classes string

Classes to add to the checkboxes container.
attributes object

HTML attributes (for example data attributes) to add to the anchor tag.
Options for formGroup
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 beforeInputs.
afterInputs object

Content to add after all checkbox items within the checkboxes component.

See afterInputs.
Options for afterInputs
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 beforeInputs
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 hint
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the hint. 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 the hint. If html is provided, the text option will be ignored.
id string

Optional ID attribute to add to the hint span tag.
classes string

Classes to add to the hint span tag.
attributes object

HTML attributes (for example data attributes) to add to the hint span tag.
Options for items
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 for the checkbox item. If omitted, then component global name string will be applied.
value string Required.

Value for the checkbox input.
label object

Subset of options for the label used by each checkbox item within the checkboxes component.

See label. See label.
hint object

Can be used to add a hint to each checkbox item within the checkboxes component.

See 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 conditional.
behaviour string

If set to "exclusive", implements a 'None of these' type behaviour via JavaScript when checkboxes are clicked.
disabled boolean

If true, checkbox will be disabled.
attributes object

HTML attributes (for example data attributes) to add to the checkbox input tag.
Options for conditional
Name Type Description
html string Required.

The HTML to reveal when the checkbox is checked.
Options for label
Name Type Description
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 label
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the 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 the label. If html is provided, the text option will be ignored.
for string

The value of the for attribute, the ID of the input the label is associated with.
isPageHeading boolean

Whether the label also acts as the heading for the page.
classes string

Classes to add to the label tag.
attributes object

HTML attributes (for example data attributes) to add to the label tag.

 
{% from "moduk/components/checkboxes/macro.njk" import modukCheckboxes -%}

{{ modukCheckboxes({
  name: "incident-not-as-page-heading",
  fieldset: {
    legend: {
      text: "Who did you report the incident to?"
    }
  },
  hint: {
    text: "Select all that apply."
  },
  items: [
    {
      value: "unit-medic",
      text: "Unit medic"
    },
    {
      value: "hospital",
      text: "Hospital"
    },
    {
      value: "chain-of-command",
      text: "Chain of command"
    },
    {
      value: "colleague",
      text: "Colleague"
    },
    {
      value: "other-person",
      text: "Other person"
    }
  ]
}) -}}

Checkbox items with hints

Open this checkboxes example in a new tab

What is your nationality?

If you have dual nationality, select all options that are relevant to you.
including English, Scottish, Welsh and Northern Irish
HTML 
<div class="govuk-form-group">
  <fieldset
    class="govuk-fieldset"
    aria-describedby="nationality-with-item-hint-hint"
  >
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
      <h1 class="govuk-fieldset__heading">What is your nationality?</h1>
    </legend>
    <div id="nationality-with-item-hint-hint" class="govuk-hint">
      If you have dual nationality, select all options that are relevant to you.
    </div>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="nationality-with-item-hint"
          name="nationality-with-item-hint"
          type="checkbox"
          value="british"
          aria-describedby="nationality-with-item-hint-item-hint"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="nationality-with-item-hint"
        >
          British
        </label>
        <div
          id="nationality-with-item-hint-item-hint"
          class="govuk-hint govuk-checkboxes__hint"
        >
          including English, Scottish, Welsh and Northern Irish
        </div>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="nationality-with-item-hint-2"
          name="nationality-with-item-hint"
          type="checkbox"
          value="irish"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="nationality-with-item-hint-2"
        >
          Irish
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="nationality-with-item-hint-3"
          name="nationality-with-item-hint"
          type="checkbox"
          value="another-country"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="nationality-with-item-hint-3"
        >
          Citizen of another country
        </label>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks
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.

Primary options
Name Type Description
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 fieldset.
hint object

Can be used to add a hint to the checkboxes component.

See 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 error message.
formGroup object

Additional options for the form group containing the checkboxes component.

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

Name attribute for all checkbox items.
items array Required.

The checkbox items within the checkboxes component.

See 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.
classes string

Classes to add to the checkboxes container.
attributes object

HTML attributes (for example data attributes) to add to the anchor tag.
Options for formGroup
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 beforeInputs.
afterInputs object

Content to add after all checkbox items within the checkboxes component.

See afterInputs.
Options for afterInputs
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 beforeInputs
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 hint
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the hint. 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 the hint. If html is provided, the text option will be ignored.
id string

Optional ID attribute to add to the hint span tag.
classes string

Classes to add to the hint span tag.
attributes object

HTML attributes (for example data attributes) to add to the hint span tag.
Options for items
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 for the checkbox item. If omitted, then component global name string will be applied.
value string Required.

Value for the checkbox input.
label object

Subset of options for the label used by each checkbox item within the checkboxes component.

See label. See label.
hint object

Can be used to add a hint to each checkbox item within the checkboxes component.

See 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 conditional.
behaviour string

If set to "exclusive", implements a 'None of these' type behaviour via JavaScript when checkboxes are clicked.
disabled boolean

If true, checkbox will be disabled.
attributes object

HTML attributes (for example data attributes) to add to the checkbox input tag.
Options for conditional
Name Type Description
html string Required.

The HTML to reveal when the checkbox is checked.
Options for label
Name Type Description
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 label
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the 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 the label. If html is provided, the text option will be ignored.
for string

The value of the for attribute, the ID of the input the label is associated with.
isPageHeading boolean

Whether the label also acts as the heading for the page.
classes string

Classes to add to the label tag.
attributes object

HTML attributes (for example data attributes) to add to the label tag.

 
{% from "moduk/components/checkboxes/macro.njk" import modukCheckboxes -%}

{{ modukCheckboxes({
  name: "nationality-with-item-hint",
  fieldset: {
    legend: {
      text: "What is your nationality?",
      isPageHeading: true,
      classes: "govuk-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: "another-country",
      text: "Citizen of another country"
    }
  ]
}) -}}

Checkbox items with a text divider

Open this checkboxes example in a new tab

Who did you report the incident to?

Select all that apply.
or
HTML 
<div class="govuk-form-group">
  <fieldset
    class="govuk-fieldset"
    aria-describedby="incident-with-none-option-hint"
  >
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
      <h1 class="govuk-fieldset__heading">
        Who did you report the incident to?
      </h1>
    </legend>
    <div id="incident-with-none-option-hint" class="govuk-hint">
      Select all that apply.
    </div>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-with-none-option"
          name="incident-with-none-option"
          type="checkbox"
          value="unit-medic"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-with-none-option"
        >
          Unit medic
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-with-none-option-2"
          name="incident-with-none-option"
          type="checkbox"
          value="hospital"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-with-none-option-2"
        >
          Hospital
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-with-none-option-3"
          name="incident-with-none-option"
          type="checkbox"
          value="chain-of-command"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-with-none-option-3"
        >
          Chain of command
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-with-none-option-4"
          name="incident-with-none-option"
          type="checkbox"
          value="colleague"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-with-none-option-4"
        >
          Colleague
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-with-none-option-5"
          name="incident-with-none-option"
          type="checkbox"
          value="other-person"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-with-none-option-5"
        >
          Other person
        </label>
      </div>
      <div class="govuk-checkboxes__divider">or</div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-with-none-option-7"
          name="incident-with-none-option"
          type="checkbox"
          value="none"
          data-behaviour="exclusive"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-with-none-option-7"
        >
          I did not report the incident
        </label>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks
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.

Primary options
Name Type Description
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 fieldset.
hint object

Can be used to add a hint to the checkboxes component.

See 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 error message.
formGroup object

Additional options for the form group containing the checkboxes component.

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

Name attribute for all checkbox items.
items array Required.

The checkbox items within the checkboxes component.

See 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.
classes string

Classes to add to the checkboxes container.
attributes object

HTML attributes (for example data attributes) to add to the anchor tag.
Options for formGroup
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 beforeInputs.
afterInputs object

Content to add after all checkbox items within the checkboxes component.

See afterInputs.
Options for afterInputs
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 beforeInputs
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 hint
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the hint. 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 the hint. If html is provided, the text option will be ignored.
id string

Optional ID attribute to add to the hint span tag.
classes string

Classes to add to the hint span tag.
attributes object

HTML attributes (for example data attributes) to add to the hint span tag.
Options for items
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 for the checkbox item. If omitted, then component global name string will be applied.
value string Required.

Value for the checkbox input.
label object

Subset of options for the label used by each checkbox item within the checkboxes component.

See label. See label.
hint object

Can be used to add a hint to each checkbox item within the checkboxes component.

See 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 conditional.
behaviour string

If set to "exclusive", implements a 'None of these' type behaviour via JavaScript when checkboxes are clicked.
disabled boolean

If true, checkbox will be disabled.
attributes object

HTML attributes (for example data attributes) to add to the checkbox input tag.
Options for conditional
Name Type Description
html string Required.

The HTML to reveal when the checkbox is checked.
Options for label
Name Type Description
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 label
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the 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 the label. If html is provided, the text option will be ignored.
for string

The value of the for attribute, the ID of the input the label is associated with.
isPageHeading boolean

Whether the label also acts as the heading for the page.
classes string

Classes to add to the label tag.
attributes object

HTML attributes (for example data attributes) to add to the label tag.

 
{% from "moduk/components/checkboxes/macro.njk" import modukCheckboxes -%}

{{ modukCheckboxes({
  name: "incident-with-none-option",
  fieldset: {
    legend: {
      text: "Who did you report the incident to?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--l"
    }
  },
  hint: {
    text: "Select all that apply."
  },
  items: [
    {
      value: "unit-medic",
      text: "Unit medic"
    },
    {
      value: "hospital",
      text: "Hospital"
    },
    {
      value: "chain-of-command",
      text: "Chain of command"
    },
    {
      value: "colleague",
      text: "Colleague"
    },
    {
      value: "other-person",
      text: "Other person"
    },
    {
      divider: "or"
    },
    {
      value: "none",
      text: "I did not report the incident",
      behaviour: "exclusive"
    }
  ]
}) -}}
Open this checkboxes example in a new tab

How would you like to be contacted?

Select all options that are relevant to you.
HTML 
<div class="govuk-form-group">
  <fieldset
    class="govuk-fieldset"
    aria-describedby="contact-with-conditional-reveal-hint"
  >
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
      <h1 class="govuk-fieldset__heading">
        How would you like to be contacted?
      </h1>
    </legend>
    <div id="contact-with-conditional-reveal-hint" class="govuk-hint">
      Select all options that are relevant to you.
    </div>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="contact-with-conditional-reveal"
          name="contact-with-conditional-reveal"
          type="checkbox"
          value="email"
          checked
          data-aria-controls="conditional-contact-with-conditional-reveal"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="contact-with-conditional-reveal"
        >
          Email
        </label>
      </div>
      <div
        class="govuk-checkboxes__conditional"
        id="conditional-contact-with-conditional-reveal"
      >
        <div class="govuk-form-group">
          <label class="govuk-label" for="contact-by-email">
            Email address
          </label>
          <input
            class="govuk-input govuk-!-width-one-third"
            id="contact-by-email"
            name="contact-by-email"
            type="email"
            spellcheck="false"
            autocomplete="email"
          />
        </div>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="contact-with-conditional-reveal-2"
          name="contact-with-conditional-reveal"
          type="checkbox"
          value="phone"
          data-aria-controls="conditional-contact-with-conditional-reveal-2"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="contact-with-conditional-reveal-2"
        >
          Phone
        </label>
      </div>
      <div
        class="govuk-checkboxes__conditional govuk-checkboxes__conditional--hidden"
        id="conditional-contact-with-conditional-reveal-2"
      >
        <div class="govuk-form-group">
          <label class="govuk-label" for="contact-by-phone">
            Phone number
          </label>
          <input
            class="govuk-input govuk-!-width-one-third"
            id="contact-by-phone"
            name="contact-by-phone"
            type="tel"
            autocomplete="tel"
          />
        </div>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="contact-with-conditional-reveal-3"
          name="contact-with-conditional-reveal"
          type="checkbox"
          value="text message"
          data-aria-controls="conditional-contact-with-conditional-reveal-3"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="contact-with-conditional-reveal-3"
        >
          Text message
        </label>
      </div>
      <div
        class="govuk-checkboxes__conditional govuk-checkboxes__conditional--hidden"
        id="conditional-contact-with-conditional-reveal-3"
      >
        <div class="govuk-form-group">
          <label class="govuk-label" for="contact-by-text">
            Mobile phone number
          </label>
          <input
            class="govuk-input govuk-!-width-one-third"
            id="contact-by-text"
            name="contact-by-text"
            type="tel"
            autocomplete="tel"
          />
        </div>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks
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.

Primary options
Name Type Description
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 fieldset.
hint object

Can be used to add a hint to the checkboxes component.

See 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 error message.
formGroup object

Additional options for the form group containing the checkboxes component.

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

Name attribute for all checkbox items.
items array Required.

The checkbox items within the checkboxes component.

See 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.
classes string

Classes to add to the checkboxes container.
attributes object

HTML attributes (for example data attributes) to add to the anchor tag.
Options for formGroup
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 beforeInputs.
afterInputs object

Content to add after all checkbox items within the checkboxes component.

See afterInputs.
Options for afterInputs
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 beforeInputs
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 hint
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the hint. 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 the hint. If html is provided, the text option will be ignored.
id string

Optional ID attribute to add to the hint span tag.
classes string

Classes to add to the hint span tag.
attributes object

HTML attributes (for example data attributes) to add to the hint span tag.
Options for items
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 for the checkbox item. If omitted, then component global name string will be applied.
value string Required.

Value for the checkbox input.
label object

Subset of options for the label used by each checkbox item within the checkboxes component.

See label. See label.
hint object

Can be used to add a hint to each checkbox item within the checkboxes component.

See 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 conditional.
behaviour string

If set to "exclusive", implements a 'None of these' type behaviour via JavaScript when checkboxes are clicked.
disabled boolean

If true, checkbox will be disabled.
attributes object

HTML attributes (for example data attributes) to add to the checkbox input tag.
Options for conditional
Name Type Description
html string Required.

The HTML to reveal when the checkbox is checked.
Options for label
Name Type Description
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 label
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the 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 the label. If html is provided, the text option will be ignored.
for string

The value of the for attribute, the ID of the input the label is associated with.
isPageHeading boolean

Whether the label also acts as the heading for the page.
classes string

Classes to add to the label tag.
attributes object

HTML attributes (for example data attributes) to add to the label tag.

 
{% from "moduk/components/checkboxes/macro.njk" import modukCheckboxes -%}
{% from "moduk/components/input/macro.njk" import modukInput -%}

{% set emailHtml %}
{{- modukInput({
  id: "contact-by-email",
  name: "contact-by-email",
  type: "email",
  autocomplete: "email",
  spellcheck: false,
  classes: "govuk-!-width-one-third",
  label: {
    text: "Email address"
  }
}) -}}
{% endset -%}

{% set phoneHtml %}
{{- modukInput({
  id: "contact-by-phone",
  name: "contact-by-phone",
  type: "tel",
  autocomplete: "tel",
  classes: "govuk-!-width-one-third",
  label: {
    text: "Phone number"
  }
}) -}}
{% endset -%}

{% set textHtml %}
{{- modukInput({
  id: "contact-by-text",
  name: "contact-by-text",
  type: "tel",
  autocomplete: "tel",
  classes: "govuk-!-width-one-third",
  label: {
    text: "Mobile phone number"
  }
}) -}}
{% endset -%}

{{ modukCheckboxes({
  name: "contact-with-conditional-reveal",
  fieldset: {
    legend: {
      text: "How would you like to be contacted?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--l"
    }
  },
  hint: {
    text: "Select all options that are relevant to you."
  },
  items: [
    {
      value: "email",
      text: "Email",
      checked: true,
      conditional: {
        html: emailHtml
      }
    },
    {
      value: "phone",
      text: "Phone",
      conditional: {
        html: phoneHtml
      }
    },
    {
      value: "text message",
      text: "Text message",
      conditional: {
        html: textHtml
      }
    }
  ]
}) -}}

Smaller checkboxes

Open this checkboxes example in a new tab

Organisation

HTML 
<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      <h1 class="govuk-fieldset__heading">Organisation</h1>
    </legend>
    <div
      class="govuk-checkboxes govuk-checkboxes--small"
      data-module="govuk-checkboxes"
    >
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="organisation-small"
          name="organisation-small"
          type="checkbox"
          value="royal-navy"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="organisation-small"
        >
          Royal Navy
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="organisation-small-2"
          name="organisation-small"
          type="checkbox"
          value="british-army"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="organisation-small-2"
        >
          British Army
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="organisation-small-3"
          name="organisation-small"
          type="checkbox"
          value="royal-air-force"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="organisation-small-3"
        >
          Royal Air Force
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="organisation-small-4"
          name="organisation-small"
          type="checkbox"
          value="strategic-command"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="organisation-small-4"
        >
          Strategic Command
        </label>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks
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.

Primary options
Name Type Description
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 fieldset.
hint object

Can be used to add a hint to the checkboxes component.

See 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 error message.
formGroup object

Additional options for the form group containing the checkboxes component.

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

Name attribute for all checkbox items.
items array Required.

The checkbox items within the checkboxes component.

See 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.
classes string

Classes to add to the checkboxes container.
attributes object

HTML attributes (for example data attributes) to add to the anchor tag.
Options for formGroup
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 beforeInputs.
afterInputs object

Content to add after all checkbox items within the checkboxes component.

See afterInputs.
Options for afterInputs
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 beforeInputs
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 hint
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the hint. 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 the hint. If html is provided, the text option will be ignored.
id string

Optional ID attribute to add to the hint span tag.
classes string

Classes to add to the hint span tag.
attributes object

HTML attributes (for example data attributes) to add to the hint span tag.
Options for items
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 for the checkbox item. If omitted, then component global name string will be applied.
value string Required.

Value for the checkbox input.
label object

Subset of options for the label used by each checkbox item within the checkboxes component.

See label. See label.
hint object

Can be used to add a hint to each checkbox item within the checkboxes component.

See 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 conditional.
behaviour string

If set to "exclusive", implements a 'None of these' type behaviour via JavaScript when checkboxes are clicked.
disabled boolean

If true, checkbox will be disabled.
attributes object

HTML attributes (for example data attributes) to add to the checkbox input tag.
Options for conditional
Name Type Description
html string Required.

The HTML to reveal when the checkbox is checked.
Options for label
Name Type Description
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 label
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the 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 the label. If html is provided, the text option will be ignored.
for string

The value of the for attribute, the ID of the input the label is associated with.
isPageHeading boolean

Whether the label also acts as the heading for the page.
classes string

Classes to add to the label tag.
attributes object

HTML attributes (for example data attributes) to add to the label tag.

 
{% from "moduk/components/checkboxes/macro.njk" import modukCheckboxes -%}

{{ modukCheckboxes({
  name: "organisation-small",
  classes: "govuk-checkboxes--small",
  fieldset: {
    legend: {
      text: "Organisation",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--m"
    }
  },
  items: [
    {
      value: "royal-navy",
      text: "Royal Navy"
    },
    {
      value: "british-army",
      text: "British Army"
    },
    {
      value: "royal-air-force",
      text: "Royal Air Force"
    },
    {
      value: "strategic-command",
      text: "Strategic Command"
    }
  ]
}) -}}

Error messages

Open this checkboxes example in a new tab

Who did you report the incident to?

Select all that apply.

Error: Select who you reported the incident to

HTML 
<div class="govuk-form-group govuk-form-group--error">
  <fieldset
    class="govuk-fieldset"
    aria-describedby="incident-with-error-message-hint incident-with-error-message-error"
  >
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
      <h1 class="govuk-fieldset__heading">
        Who did you report the incident to?
      </h1>
    </legend>
    <div id="incident-with-error-message-hint" class="govuk-hint">
      Select all that apply.
    </div>
    <p id="incident-with-error-message-error" class="govuk-error-message">
      <span class="govuk-visually-hidden">Error:</span> Select who you reported
      the incident to
    </p>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-with-error-message"
          name="incident-with-error-message"
          type="checkbox"
          value="unit-medic"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-with-error-message"
        >
          Unit medic
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-with-error-message-2"
          name="incident-with-error-message"
          type="checkbox"
          value="hospital"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-with-error-message-2"
        >
          Hospital
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-with-error-message-3"
          name="incident-with-error-message"
          type="checkbox"
          value="chain-of-command"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-with-error-message-3"
        >
          Chain of command
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-with-error-message-4"
          name="incident-with-error-message"
          type="checkbox"
          value="colleague"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-with-error-message-4"
        >
          Colleague
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input
          class="govuk-checkboxes__input"
          id="incident-with-error-message-5"
          name="incident-with-error-message"
          type="checkbox"
          value="other-person"
        />
        <label
          class="govuk-label govuk-checkboxes__label"
          for="incident-with-error-message-5"
        >
          Other person
        </label>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks
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.

Primary options
Name Type Description
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 fieldset.
hint object

Can be used to add a hint to the checkboxes component.

See 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 error message.
formGroup object

Additional options for the form group containing the checkboxes component.

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

Name attribute for all checkbox items.
items array Required.

The checkbox items within the checkboxes component.

See 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.
classes string

Classes to add to the checkboxes container.
attributes object

HTML attributes (for example data attributes) to add to the anchor tag.
Options for formGroup
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 beforeInputs.
afterInputs object

Content to add after all checkbox items within the checkboxes component.

See afterInputs.
Options for afterInputs
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 beforeInputs
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 hint
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the hint. 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 the hint. If html is provided, the text option will be ignored.
id string

Optional ID attribute to add to the hint span tag.
classes string

Classes to add to the hint span tag.
attributes object

HTML attributes (for example data attributes) to add to the hint span tag.
Options for items
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 for the checkbox item. If omitted, then component global name string will be applied.
value string Required.

Value for the checkbox input.
label object

Subset of options for the label used by each checkbox item within the checkboxes component.

See label. See label.
hint object

Can be used to add a hint to each checkbox item within the checkboxes component.

See 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 conditional.
behaviour string

If set to "exclusive", implements a 'None of these' type behaviour via JavaScript when checkboxes are clicked.
disabled boolean

If true, checkbox will be disabled.
attributes object

HTML attributes (for example data attributes) to add to the checkbox input tag.
Options for conditional
Name Type Description
html string Required.

The HTML to reveal when the checkbox is checked.
Options for label
Name Type Description
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 label
Name Type Description
text string Required.

If html is set, this is not required. Text to use within the 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 the label. If html is provided, the text option will be ignored.
for string

The value of the for attribute, the ID of the input the label is associated with.
isPageHeading boolean

Whether the label also acts as the heading for the page.
classes string

Classes to add to the label tag.
attributes object

HTML attributes (for example data attributes) to add to the label tag.

 
{% from "moduk/components/checkboxes/macro.njk" import modukCheckboxes -%}

{{ modukCheckboxes({
  name: "incident-with-error-message",
  fieldset: {
    legend: {
      text: "Who did you report the incident to?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--l"
    }
  },
  hint: {
    text: "Select all that apply."
  },
  errorMessage: {
    text: "Select who you reported the incident to"
  },
  items: [
    {
      value: "unit-medic",
      text: "Unit medic"
    },
    {
      value: "hospital",
      text: "Hospital"
    },
    {
      value: "chain-of-command",
      text: "Chain of command"
    },
    {
      value: "colleague",
      text: "Colleague"
    },
    {
      value: "other-person",
      text: "Other person"
    }
  ]
}) -}}

Changes from the GOV.UK version

MOD.UK Design System components are closely based on GOV.UK Design System components.

For this component we’ve changed the font.

Have you tested this component?

Let us know how we could improve this component or share your user research findings.

Email the MOD.UK Design System team at design-system@digital.mod.uk

Need help?

Email the MOD.UK Design System team at design-system@digital.mod.uk if you have questions or feedback.