Skip to main content

Testing

Help us to improve the ONS Design System. Take part in a short study

Checkboxes

Checkboxes let the user select one or more options from a list.

<div class="question">
  <fieldset class="fieldset">
    <legend class="fieldset__legend">
      <h1 id="fieldset-legend-title" class="fieldset__legend-title ">What devices do you own?</h1>
    </legend>
    <div class="input-items">
      <p class="checkboxes__label">Select all that apply</p>
      <div class="checkboxes__items">
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="mobile-phone" class="checkbox__input js-checkbox " value="mobile-phone">
            <label class="checkbox__label  " for="mobile-phone" id="mobile-phone-label">Mobile phone
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="tablet" class="checkbox__input js-checkbox " value="tablet">
            <label class="checkbox__label  " for="tablet" id="tablet-label">Tablet
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="laptop" class="checkbox__input js-checkbox " value="laptop">
            <label class="checkbox__label  " for="laptop" id="laptop-label">Laptop
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="desktop" class="checkbox__input js-checkbox " value="desktop">
            <label class="checkbox__label  " for="desktop" id="desktop-label">Desktop computer
            </label>
          </span>
        </p>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks macro options
Name Type Required Description
id string false Id to apply to the fieldset
classes string false Classes to apply to the fieldset
legend string false The legend to apply to the fieldset
legendClasses string false Classes to apply to the legend
name string true The name to apply to the checkboxes
checkboxes Array<Checkbox> true An array of checkboxes to render
mutuallyExclusive MutuallyExclusive (ref) false Configuration object if this is a mutually exclusive checkbox list
dontWrap boolean false Prevents the checkboxes from being wrapped in a fieldset component
legendIsQuestionTitle boolean false Creates a h1 inside the legend (further information)
open boolean false Whether the ‘other’ input should be displayed

Checkbox

Name Type Required Description
id string true The id of the checkbox
name string true The name of the checkbox
value string true The value of the checkbox
classes string false Classes to apply to the checkbox
inputClasses string false Classes to apply to the checkbox input
checked boolean false Whether the checkbox should be checked
label Label (ref) true Settings for the checkbox label
other Input (ref) or Select (ref) false Object with settings for other input or select
otherType string false (true if other provided) Can be set to select or input to set what other input you want in a radio
attributes object false HTML attributes (for example data attributes) to add to the checkbox input element
error Error (ref) false Configuration for validation errors
deselectMessage string false For use with mutually exclusive checkboxes. The text the aria-live will read to warn that selecting the exclusive option will clear all other inputs errors
{% from "components/question/_macro.njk" import onsQuestion %}
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{% call onsQuestion({
    "title": "What devices do you own?",
    "legendIsQuestionTitle": true
}) %}
    {{
        onsCheckboxes({
            "checkboxesLabel": "Select all that apply",
            "dontWrap": true,
            "name": "devices",
            "checkboxes": [
                {
                    "id": "mobile-phone",
                    "label": {
                        "text": "Mobile phone"
                    },
                    "value": "mobile-phone"
                },
                {
                    "id": "tablet",
                    "label": {
                        "text": "Tablet"
                    },
                    "value": "tablet"
                },
                {
                    "id": "laptop",
                    "label": {
                        "text": "Laptop"
                    },
                    "value": "laptop"
                },
                {
                    "id": "desktop",
                    "label": {
                        "text": "Desktop computer"
                    },
                    "value": "desktop"
                }
            ]
        })
    }}
{% endcall %}

{% macro onsCheckboxes(params) %}
    {% from "components/fieldset/_macro.njk" import onsFieldset %}
    {% from "components/mutually-exclusive/_macro.njk" import onsMutuallyExclusive %}
    {% from "components/checkboxes/_checkbox-macro.njk" import onsCheckbox %}
    {% set fields %}
        <p class="checkboxes__label">{{ params.checkboxesLabel }}</p>
        <div class="checkboxes__items">
            {% for checkbox in params.checkboxes %}
                {% set labelHTML = checkbox.label.text %}
                {% if params.mutuallyExclusive is defined and params.mutuallyExclusive %}
                    {% set exclusiveClass = ' js-exclusive-group-item' %}
                {% endif %}
                <p class="checkboxes__item">
                    {% set config = {
                        "id": checkbox.id,
                        "name": checkbox.name,
                        "value": checkbox.value,
                        "checked": checkbox.checked,
                        "classes": checkbox.classes,
                        "inputClasses": exclusiveClass,
                        "label": {
                            "for": checkbox.id,
                            "text": labelHTML,
                            "description": checkbox.label.description,
                            "classes": checkbox.label.classes | default('')
                        },
                        "attributes": checkbox.attributes
                    } %}
                    {% if checkbox.other is defined and checkbox.other %}
                        {% set config = config | setAttributes({
                            "other": {
                                "open": checkbox.other.open | default(false),
                                "id": checkbox.other.id,
                                "name": checkbox.other.name,
                                "type": checkbox.other.type,
                                "otherType": checkbox.other.otherType,
                                "options": checkbox.other.options,
                                "classes": checkbox.other.classes | default('') + exclusiveClass | default(''),
                                "attributes": checkbox.other.attributes,
                                "label": {
                                    "text": checkbox.other.label.text
                                },
                                "value": checkbox.other.value
                            }
                        }) %}
                    {% endif %}
                    {{ onsCheckbox(config) }}
                </p>
                {% if not loop.last %}
                    <br>
                {% endif %}
            {% endfor %}
        </div>
    {% endset %}
    {% if params.mutuallyExclusive is defined and params.mutuallyExclusive %}
        {% call onsMutuallyExclusive({
            "id": params.id,
            "description": params.description,
            "classes": params.classes,
            "legend": params.legend,
            "legendClasses": params.legendClasses,
            "description": params.description,
            "attributes": params.attributes,
            "dontWrap": params.dontWrap,
            "legendIsQuestionTitle": params.legendIsQuestionTitle,
            "checkbox": params.mutuallyExclusive.checkbox,
            "or": params.mutuallyExclusive.or,
            "deselectMessage": params.mutuallyExclusive.deselectMessage,
            "deselectGroupAdjective": params.mutuallyExclusive.deselectGroupAdjective,
            "deselectCheckboxAdjective": params.mutuallyExclusive.deselectCheckboxAdjective,
            "error": params.error
        }) %}
            {{ fields | safe }}
        {% endcall %}
    {% else %}
        {% call onsFieldset({
            "id": params.id,
            "description": params.description,
            "classes": params.classes,
            "legend": params.legend,
            "legendClasses": params.legendClasses,
            "legendIsQuestionTitle": params.legendIsQuestionTitle,
            "description": params.description,
            "attributes": params.attributes,
            "dontWrap": params.dontWrap,
            "error": params.error
        }) %}
            {{ fields | safe }}
        {% endcall %}
    {% endif %}
{% endmacro %}

$checkbox-input-width: 22px;
$checkbox-padding: 11px;
.checkbox {
  display: inline-block;
  position: relative;
  width: 100%;
  z-index: 1;
  &__input {
    appearance: none;
    background: url(#{$static}/img/icons--check.svg) no-repeat center center;
    background-color: $color-white;
    background-size: 0;
    border: 2px solid $color-input;
    border-radius: 0.2rem;
    box-sizing: border-box;
    height: $checkbox-input-width;
    left: $checkbox-padding;
    position: absolute;
    top: $checkbox-padding + 3px;
    width: $checkbox-input-width;
    z-index: 1;
    &:focus,
    &:checked {
      outline: none;
    }
    &:checked {
      background-size: 14px;
    }
  }
  &__label {
    cursor: pointer;
    display: block;
    padding: $checkbox-padding 1rem $checkbox-padding ($checkbox-padding * 2 + $checkbox-input-width);
    width: 100%;
    &--with-description {
      padding: 0 1rem $checkbox-padding 0;
    }
    .label__description {
      margin-left: -1.75rem;
    }
    &::before {
      background: $color-white;
      border: 1px solid $color-input;
      border-radius: 3px;
      bottom: 0;
      content: '';
      left: 0;
      position: absolute;
      right: 0;
      top: 0;
      z-index: -1;
    }
    * {
      pointer-events: none;
    }
  }
  &__description {
    display: block;
    margin-top: 0.25rem;
  }
  &__other {
    display: block;
    padding: 0 $checkbox-padding $checkbox-padding;
  }
  &__input:checked + &__label::before {
    background: $color-grey-5;
    box-shadow: 0 0 0 1px $color-input;
  }
  .panel--error .radio__input:checked ~ &__other > .input--text:required:not(:focus) {
    border: 1px solid $color-ruby-red;
    outline: 1px solid $color-ruby-red;
    outline-offset: -2px;
  }
  &__input:focus + &__label::before {
    @extend .input:focus;
  }
  &__input:not(:checked) ~ &__other {
    display: none;
  }
  &__input:not(:checked) ~ &__other--open {
    display: block;
  }
  &--toggle & {
    &__input {
      left: 0;
      top: 0.1rem;
      &:focus {
        box-shadow: 0 0 0 3px $color-focus;
      }
    }
    &__label {
      padding: 0 0 0 ($checkbox-input-width + $checkbox-padding);
      &::before {
        background: none;
        border: 0;
      }
    }
    &__input:checked + .checkbox__label::before,
    &__input:focus + .checkbox__label::before {
      background: transparent;
      box-shadow: none;
    }
    &__input:focus + .checkbox__label::before {
      border: 0;
      outline: none;
    }
  }
}
.checkboxes {
  &__label {
    display: block;
    margin: 0 0 0.5rem;
  }
  &__items {
    display: block;
  }
  &__item {
    display: inline-block;
    margin: 0 0 0.5rem;
    width: 100%;
    &:last-child {
      margin-bottom: 0;
    }
    @include mq(s) {
      min-width: 20rem;
      width: auto;
    }
  }
  &--mutually-exclusive__item {
    @extend .checkboxes__item;
    margin-bottom: 0;
  }
}

When to use this component

Use the checkboxes component when you need to help users select multiple options from a list.

When not to use this component

Do not use the checkboxes component if users can only choose one option from a list. In this case, use the radios component.

How to use this component

Checkboxes are grouped within a fieldset which starts with a <legend> which lets the user know what they need to do.

Variants

Checkbox with input

This variant lets the user provide an answer other to the options in the list, or to provide additional information required to describe their answer.

Use this variation by wrapping the text field in a div with class checkbox__other, added directly after the checkbox label. CSS hides this field until the checkbox is :checked.

<div class="question">
  <fieldset class="fieldset">
    <legend class="fieldset__legend">
      <h1 id="fieldset-legend-title" class="fieldset__legend-title ">Do you have any dietary requirements?</h1>
    </legend>
    <div class="input-items">
      <p class="checkboxes__label">Select all that apply</p>
      <div class="checkboxes__items">
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="gluten-free" class="checkbox__input js-checkbox " value="gluten-free">
            <label class="checkbox__label  " for="gluten-free" id="gluten-free-label">Gluten free
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="lactose-intolerant" class="checkbox__input js-checkbox " value="lactose-intolerant">
            <label class="checkbox__label  " for="lactose-intolerant" id="lactose-intolerant-label">Lactose intolerant
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="vegan" class="checkbox__input js-checkbox " value="vegan">
            <label class="checkbox__label  " for="vegan" id="vegan-label">Vegan
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="vegetarian" class="checkbox__input js-checkbox " value="vegetarian">
            <label class="checkbox__label  " for="vegetarian" id="vegetarian-label">Vegetarian
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="other-checkbox" class="checkbox__input js-checkbox " value="other" aria-controls="other-checkbox-other-wrap" aria-haspopup="true">
            <label class="checkbox__label  " for="other-checkbox" id="other-checkbox-label">Other
            </label>
            <span class="checkbox__other" id="other-checkbox-other-wrap">
              <label class="label u-fs-s--b " for="other-textbox" id="other-textbox-label">Enter dietary requirements
              </label>
              <input type="text" id="other-textbox" class="input input--text input-type__input input--w-auto " name="other-answer" />
            </span>
          </span>
        </p>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks macro options
Name Type Required Description
id string false Id to apply to the fieldset
classes string false Classes to apply to the fieldset
legend string false The legend to apply to the fieldset
legendClasses string false Classes to apply to the legend
name string true The name to apply to the checkboxes
checkboxes Array<Checkbox> true An array of checkboxes to render
mutuallyExclusive MutuallyExclusive (ref) false Configuration object if this is a mutually exclusive checkbox list
dontWrap boolean false Prevents the checkboxes from being wrapped in a fieldset component
legendIsQuestionTitle boolean false Creates a h1 inside the legend (further information)
open boolean false Whether the ‘other’ input should be displayed

Checkbox

Name Type Required Description
id string true The id of the checkbox
name string true The name of the checkbox
value string true The value of the checkbox
classes string false Classes to apply to the checkbox
inputClasses string false Classes to apply to the checkbox input
checked boolean false Whether the checkbox should be checked
label Label (ref) true Settings for the checkbox label
other Input (ref) or Select (ref) false Object with settings for other input or select
otherType string false (true if other provided) Can be set to select or input to set what other input you want in a radio
attributes object false HTML attributes (for example data attributes) to add to the checkbox input element
error Error (ref) false Configuration for validation errors
deselectMessage string false For use with mutually exclusive checkboxes. The text the aria-live will read to warn that selecting the exclusive option will clear all other inputs errors
{% from "components/question/_macro.njk" import onsQuestion %}
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{% call onsQuestion({
    "title": "Do you have any dietary requirements?",
    "legendIsQuestionTitle": true
}) %}
    {{
        onsCheckboxes({
            "checkboxesLabel": "Select all that apply",
            "dontWrap": true,
            "name": "dietary",
            "checkboxes": [
                {
                    "id": "gluten-free",
                    "label": {
                        "text": "Gluten free"
                    },
                    "value": "gluten-free"
                },
                {
                    "id": "lactose-intolerant",
                    "label": {
                        "text": "Lactose intolerant"
                    },
                    "value": "lactose-intolerant"
                },
                {
                    "id": "vegan",
                    "label": {
                        "text": "Vegan"
                    },
                    "value": "vegan"
                },
                {
                    "id": "vegetarian",
                    "label": {
                        "text": "Vegetarian"
                    },
                    "value": "vegetarian"
                },
                {
                    "id": "other-checkbox",
                    "label": {
                        "text": "Other"
                    },
                    "value": "other",
                    "other": {
                        "id": "other-textbox",
                        "name": "other-answer",
                        "label": {
                            "text": "Enter dietary requirements"
                        }
                    }
                }
            ]
        })
    }}
{% endcall %}

{% macro onsCheckboxes(params) %}
    {% from "components/fieldset/_macro.njk" import onsFieldset %}
    {% from "components/mutually-exclusive/_macro.njk" import onsMutuallyExclusive %}
    {% from "components/checkboxes/_checkbox-macro.njk" import onsCheckbox %}
    {% set fields %}
        <p class="checkboxes__label">{{ params.checkboxesLabel }}</p>
        <div class="checkboxes__items">
            {% for checkbox in params.checkboxes %}
                {% set labelHTML = checkbox.label.text %}
                {% if params.mutuallyExclusive is defined and params.mutuallyExclusive %}
                    {% set exclusiveClass = ' js-exclusive-group-item' %}
                {% endif %}
                <p class="checkboxes__item">
                    {% set config = {
                        "id": checkbox.id,
                        "name": checkbox.name,
                        "value": checkbox.value,
                        "checked": checkbox.checked,
                        "classes": checkbox.classes,
                        "inputClasses": exclusiveClass,
                        "label": {
                            "for": checkbox.id,
                            "text": labelHTML,
                            "description": checkbox.label.description,
                            "classes": checkbox.label.classes | default('')
                        },
                        "attributes": checkbox.attributes
                    } %}
                    {% if checkbox.other is defined and checkbox.other %}
                        {% set config = config | setAttributes({
                            "other": {
                                "open": checkbox.other.open | default(false),
                                "id": checkbox.other.id,
                                "name": checkbox.other.name,
                                "type": checkbox.other.type,
                                "otherType": checkbox.other.otherType,
                                "options": checkbox.other.options,
                                "classes": checkbox.other.classes | default('') + exclusiveClass | default(''),
                                "attributes": checkbox.other.attributes,
                                "label": {
                                    "text": checkbox.other.label.text
                                },
                                "value": checkbox.other.value
                            }
                        }) %}
                    {% endif %}
                    {{ onsCheckbox(config) }}
                </p>
                {% if not loop.last %}
                    <br>
                {% endif %}
            {% endfor %}
        </div>
    {% endset %}
    {% if params.mutuallyExclusive is defined and params.mutuallyExclusive %}
        {% call onsMutuallyExclusive({
            "id": params.id,
            "description": params.description,
            "classes": params.classes,
            "legend": params.legend,
            "legendClasses": params.legendClasses,
            "description": params.description,
            "attributes": params.attributes,
            "dontWrap": params.dontWrap,
            "legendIsQuestionTitle": params.legendIsQuestionTitle,
            "checkbox": params.mutuallyExclusive.checkbox,
            "or": params.mutuallyExclusive.or,
            "deselectMessage": params.mutuallyExclusive.deselectMessage,
            "deselectGroupAdjective": params.mutuallyExclusive.deselectGroupAdjective,
            "deselectCheckboxAdjective": params.mutuallyExclusive.deselectCheckboxAdjective,
            "error": params.error
        }) %}
            {{ fields | safe }}
        {% endcall %}
    {% else %}
        {% call onsFieldset({
            "id": params.id,
            "description": params.description,
            "classes": params.classes,
            "legend": params.legend,
            "legendClasses": params.legendClasses,
            "legendIsQuestionTitle": params.legendIsQuestionTitle,
            "description": params.description,
            "attributes": params.attributes,
            "dontWrap": params.dontWrap,
            "error": params.error
        }) %}
            {{ fields | safe }}
        {% endcall %}
    {% endif %}
{% endmacro %}

$checkbox-input-width: 22px;
$checkbox-padding: 11px;
.checkbox {
  display: inline-block;
  position: relative;
  width: 100%;
  z-index: 1;
  &__input {
    appearance: none;
    background: url(#{$static}/img/icons--check.svg) no-repeat center center;
    background-color: $color-white;
    background-size: 0;
    border: 2px solid $color-input;
    border-radius: 0.2rem;
    box-sizing: border-box;
    height: $checkbox-input-width;
    left: $checkbox-padding;
    position: absolute;
    top: $checkbox-padding + 3px;
    width: $checkbox-input-width;
    z-index: 1;
    &:focus,
    &:checked {
      outline: none;
    }
    &:checked {
      background-size: 14px;
    }
  }
  &__label {
    cursor: pointer;
    display: block;
    padding: $checkbox-padding 1rem $checkbox-padding ($checkbox-padding * 2 + $checkbox-input-width);
    width: 100%;
    &--with-description {
      padding: 0 1rem $checkbox-padding 0;
    }
    .label__description {
      margin-left: -1.75rem;
    }
    &::before {
      background: $color-white;
      border: 1px solid $color-input;
      border-radius: 3px;
      bottom: 0;
      content: '';
      left: 0;
      position: absolute;
      right: 0;
      top: 0;
      z-index: -1;
    }
    * {
      pointer-events: none;
    }
  }
  &__description {
    display: block;
    margin-top: 0.25rem;
  }
  &__other {
    display: block;
    padding: 0 $checkbox-padding $checkbox-padding;
  }
  &__input:checked + &__label::before {
    background: $color-grey-5;
    box-shadow: 0 0 0 1px $color-input;
  }
  .panel--error .radio__input:checked ~ &__other > .input--text:required:not(:focus) {
    border: 1px solid $color-ruby-red;
    outline: 1px solid $color-ruby-red;
    outline-offset: -2px;
  }
  &__input:focus + &__label::before {
    @extend .input:focus;
  }
  &__input:not(:checked) ~ &__other {
    display: none;
  }
  &__input:not(:checked) ~ &__other--open {
    display: block;
  }
  &--toggle & {
    &__input {
      left: 0;
      top: 0.1rem;
      &:focus {
        box-shadow: 0 0 0 3px $color-focus;
      }
    }
    &__label {
      padding: 0 0 0 ($checkbox-input-width + $checkbox-padding);
      &::before {
        background: none;
        border: 0;
      }
    }
    &__input:checked + .checkbox__label::before,
    &__input:focus + .checkbox__label::before {
      background: transparent;
      box-shadow: none;
    }
    &__input:focus + .checkbox__label::before {
      border: 0;
      outline: none;
    }
  }
}
.checkboxes {
  &__label {
    display: block;
    margin: 0 0 0.5rem;
  }
  &__items {
    display: block;
  }
  &__item {
    display: inline-block;
    margin: 0 0 0.5rem;
    width: 100%;
    &:last-child {
      margin-bottom: 0;
    }
    @include mq(s) {
      min-width: 20rem;
      width: auto;
    }
  }
  &--mutually-exclusive__item {
    @extend .checkboxes__item;
    margin-bottom: 0;
  }
}

Checkbox with visible input

This variant of “checkbox with input” shows the input instead of waiting for the checkbox to be :checked.

<div class="question">
  <fieldset class="fieldset">
    <legend class="fieldset__legend">
      <h1 id="fieldset-legend-title" class="fieldset__legend-title ">Do you have any dietary requirements?</h1>
    </legend>
    <div class="input-items">
      <p class="checkboxes__label">Select all that apply</p>
      <div class="checkboxes__items">
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="gluten-free" class="checkbox__input js-checkbox " value="gluten-free">
            <label class="checkbox__label  " for="gluten-free" id="gluten-free-label">Gluten free
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="lactose-intolerant" class="checkbox__input js-checkbox " value="lactose-intolerant">
            <label class="checkbox__label  " for="lactose-intolerant" id="lactose-intolerant-label">Lactose intolerant
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="vegan" class="checkbox__input js-checkbox " value="vegan">
            <label class="checkbox__label  " for="vegan" id="vegan-label">Vegan
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="vegetarian" class="checkbox__input js-checkbox " value="vegetarian">
            <label class="checkbox__label  " for="vegetarian" id="vegetarian-label">Vegetarian
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="other-checkbox" class="checkbox__input js-checkbox " value="other">
            <label class="checkbox__label  " for="other-checkbox" id="other-checkbox-label">Other
            </label>
            <span class="checkbox__other checkbox__other--open" id="other-checkbox-other-wrap">
              <label class="label u-fs-s--b " for="other-textbox" id="other-textbox-label">Enter dietary requirements
              </label>
              <input type="text" id="other-textbox" class="input input--text input-type__input input--w-auto " name="other-answer" />
            </span>
          </span>
        </p>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks macro options
Name Type Required Description
id string false Id to apply to the fieldset
classes string false Classes to apply to the fieldset
legend string false The legend to apply to the fieldset
legendClasses string false Classes to apply to the legend
name string true The name to apply to the checkboxes
checkboxes Array<Checkbox> true An array of checkboxes to render
mutuallyExclusive MutuallyExclusive (ref) false Configuration object if this is a mutually exclusive checkbox list
dontWrap boolean false Prevents the checkboxes from being wrapped in a fieldset component
legendIsQuestionTitle boolean false Creates a h1 inside the legend (further information)
open boolean false Whether the ‘other’ input should be displayed

Checkbox

Name Type Required Description
id string true The id of the checkbox
name string true The name of the checkbox
value string true The value of the checkbox
classes string false Classes to apply to the checkbox
inputClasses string false Classes to apply to the checkbox input
checked boolean false Whether the checkbox should be checked
label Label (ref) true Settings for the checkbox label
other Input (ref) or Select (ref) false Object with settings for other input or select
otherType string false (true if other provided) Can be set to select or input to set what other input you want in a radio
attributes object false HTML attributes (for example data attributes) to add to the checkbox input element
error Error (ref) false Configuration for validation errors
deselectMessage string false For use with mutually exclusive checkboxes. The text the aria-live will read to warn that selecting the exclusive option will clear all other inputs errors
{% from "components/question/_macro.njk" import onsQuestion %}
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{% call onsQuestion({
    "title": "Do you have any dietary requirements?",
    "legendIsQuestionTitle": true
}) %}
    {{
        onsCheckboxes({
            "checkboxesLabel": "Select all that apply",
            "dontWrap": true,
            "name": "dietary",
            "checkboxes": [
                {
                    "id": "gluten-free",
                    "label": {
                        "text": "Gluten free"
                    },
                    "value": "gluten-free"
                },
                {
                    "id": "lactose-intolerant",
                    "label": {
                        "text": "Lactose intolerant"
                    },
                    "value": "lactose-intolerant"
                },
                {
                    "id": "vegan",
                    "label": {
                        "text": "Vegan"
                    },
                    "value": "vegan"
                },
                {
                    "id": "vegetarian",
                    "label": {
                        "text": "Vegetarian"
                    },
                    "value": "vegetarian"
                },
                {
                    "id": "other-checkbox",
                    "label": {
                        "text": "Other"
                    },
                    "value": "other",
                    "other": {
                        "open": true,
                        "id": "other-textbox",
                        "name": "other-answer",
                        "label": {
                            "text": "Enter dietary requirements"
                        }
                    }
                }
            ]
        })
    }}
{% endcall %}

{% macro onsCheckboxes(params) %}
    {% from "components/fieldset/_macro.njk" import onsFieldset %}
    {% from "components/mutually-exclusive/_macro.njk" import onsMutuallyExclusive %}
    {% from "components/checkboxes/_checkbox-macro.njk" import onsCheckbox %}
    {% set fields %}
        <p class="checkboxes__label">{{ params.checkboxesLabel }}</p>
        <div class="checkboxes__items">
            {% for checkbox in params.checkboxes %}
                {% set labelHTML = checkbox.label.text %}
                {% if params.mutuallyExclusive is defined and params.mutuallyExclusive %}
                    {% set exclusiveClass = ' js-exclusive-group-item' %}
                {% endif %}
                <p class="checkboxes__item">
                    {% set config = {
                        "id": checkbox.id,
                        "name": checkbox.name,
                        "value": checkbox.value,
                        "checked": checkbox.checked,
                        "classes": checkbox.classes,
                        "inputClasses": exclusiveClass,
                        "label": {
                            "for": checkbox.id,
                            "text": labelHTML,
                            "description": checkbox.label.description,
                            "classes": checkbox.label.classes | default('')
                        },
                        "attributes": checkbox.attributes
                    } %}
                    {% if checkbox.other is defined and checkbox.other %}
                        {% set config = config | setAttributes({
                            "other": {
                                "open": checkbox.other.open | default(false),
                                "id": checkbox.other.id,
                                "name": checkbox.other.name,
                                "type": checkbox.other.type,
                                "otherType": checkbox.other.otherType,
                                "options": checkbox.other.options,
                                "classes": checkbox.other.classes | default('') + exclusiveClass | default(''),
                                "attributes": checkbox.other.attributes,
                                "label": {
                                    "text": checkbox.other.label.text
                                },
                                "value": checkbox.other.value
                            }
                        }) %}
                    {% endif %}
                    {{ onsCheckbox(config) }}
                </p>
                {% if not loop.last %}
                    <br>
                {% endif %}
            {% endfor %}
        </div>
    {% endset %}
    {% if params.mutuallyExclusive is defined and params.mutuallyExclusive %}
        {% call onsMutuallyExclusive({
            "id": params.id,
            "description": params.description,
            "classes": params.classes,
            "legend": params.legend,
            "legendClasses": params.legendClasses,
            "description": params.description,
            "attributes": params.attributes,
            "dontWrap": params.dontWrap,
            "legendIsQuestionTitle": params.legendIsQuestionTitle,
            "checkbox": params.mutuallyExclusive.checkbox,
            "or": params.mutuallyExclusive.or,
            "deselectMessage": params.mutuallyExclusive.deselectMessage,
            "deselectGroupAdjective": params.mutuallyExclusive.deselectGroupAdjective,
            "deselectCheckboxAdjective": params.mutuallyExclusive.deselectCheckboxAdjective,
            "error": params.error
        }) %}
            {{ fields | safe }}
        {% endcall %}
    {% else %}
        {% call onsFieldset({
            "id": params.id,
            "description": params.description,
            "classes": params.classes,
            "legend": params.legend,
            "legendClasses": params.legendClasses,
            "legendIsQuestionTitle": params.legendIsQuestionTitle,
            "description": params.description,
            "attributes": params.attributes,
            "dontWrap": params.dontWrap,
            "error": params.error
        }) %}
            {{ fields | safe }}
        {% endcall %}
    {% endif %}
{% endmacro %}

$checkbox-input-width: 22px;
$checkbox-padding: 11px;
.checkbox {
  display: inline-block;
  position: relative;
  width: 100%;
  z-index: 1;
  &__input {
    appearance: none;
    background: url(#{$static}/img/icons--check.svg) no-repeat center center;
    background-color: $color-white;
    background-size: 0;
    border: 2px solid $color-input;
    border-radius: 0.2rem;
    box-sizing: border-box;
    height: $checkbox-input-width;
    left: $checkbox-padding;
    position: absolute;
    top: $checkbox-padding + 3px;
    width: $checkbox-input-width;
    z-index: 1;
    &:focus,
    &:checked {
      outline: none;
    }
    &:checked {
      background-size: 14px;
    }
  }
  &__label {
    cursor: pointer;
    display: block;
    padding: $checkbox-padding 1rem $checkbox-padding ($checkbox-padding * 2 + $checkbox-input-width);
    width: 100%;
    &--with-description {
      padding: 0 1rem $checkbox-padding 0;
    }
    .label__description {
      margin-left: -1.75rem;
    }
    &::before {
      background: $color-white;
      border: 1px solid $color-input;
      border-radius: 3px;
      bottom: 0;
      content: '';
      left: 0;
      position: absolute;
      right: 0;
      top: 0;
      z-index: -1;
    }
    * {
      pointer-events: none;
    }
  }
  &__description {
    display: block;
    margin-top: 0.25rem;
  }
  &__other {
    display: block;
    padding: 0 $checkbox-padding $checkbox-padding;
  }
  &__input:checked + &__label::before {
    background: $color-grey-5;
    box-shadow: 0 0 0 1px $color-input;
  }
  .panel--error .radio__input:checked ~ &__other > .input--text:required:not(:focus) {
    border: 1px solid $color-ruby-red;
    outline: 1px solid $color-ruby-red;
    outline-offset: -2px;
  }
  &__input:focus + &__label::before {
    @extend .input:focus;
  }
  &__input:not(:checked) ~ &__other {
    display: none;
  }
  &__input:not(:checked) ~ &__other--open {
    display: block;
  }
  &--toggle & {
    &__input {
      left: 0;
      top: 0.1rem;
      &:focus {
        box-shadow: 0 0 0 3px $color-focus;
      }
    }
    &__label {
      padding: 0 0 0 ($checkbox-input-width + $checkbox-padding);
      &::before {
        background: none;
        border: 0;
      }
    }
    &__input:checked + .checkbox__label::before,
    &__input:focus + .checkbox__label::before {
      background: transparent;
      box-shadow: none;
    }
    &__input:focus + .checkbox__label::before {
      border: 0;
      outline: none;
    }
  }
}
.checkboxes {
  &__label {
    display: block;
    margin: 0 0 0.5rem;
  }
  &__items {
    display: block;
  }
  &__item {
    display: inline-block;
    margin: 0 0 0.5rem;
    width: 100%;
    &:last-child {
      margin-bottom: 0;
    }
    @include mq(s) {
      min-width: 20rem;
      width: auto;
    }
  }
  &--mutually-exclusive__item {
    @extend .checkboxes__item;
    margin-bottom: 0;
  }
}

Checkbox with drop-down

This variant uses a select component instead of an input.

<div class="question">
  <fieldset class="fieldset">
    <legend class="fieldset__legend">
      <h1 id="fieldset-legend-title" class="fieldset__legend-title ">How would you like us to contact you?</h1>
    </legend>
    <div class="input-items">
      <p class="checkboxes__label">Select all that apply</p>
      <div class="checkboxes__items">
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="post" class="checkbox__input js-checkbox " value="post">
            <label class="checkbox__label  " for="post" id="post-label">By post
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="email" class="checkbox__input js-checkbox " value="email">
            <label class="checkbox__label  " for="email" id="email-label">By email
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="phone" class="checkbox__input js-checkbox " value="phone" aria-controls="phone-other-wrap" aria-haspopup="true">
            <label class="checkbox__label  " for="phone" id="phone-label">By phone
            </label>
            <span class="checkbox__other" id="phone-other-wrap">
              <label class="label u-fs-s--b " for="phone-time">Choose preferred time of day
              </label>
              <select id="phone-time" name="phone-time" class="input input--select">
                <option value="" selected disabled>Select an option</option>
                <option value="anytime">Anytime of day</option>
                <option value="morning">Morning</option>
                <option value="afternoon">Afternoon</option>
                <option value="evening">Evening</option>
              </select>
            </span>
          </span>
        </p>
      </div>
    </div>
  </fieldset>
</div>
Nunjucks macro options
Name Type Required Description
id string false Id to apply to the fieldset
classes string false Classes to apply to the fieldset
legend string false The legend to apply to the fieldset
legendClasses string false Classes to apply to the legend
name string true The name to apply to the checkboxes
checkboxes Array<Checkbox> true An array of checkboxes to render
mutuallyExclusive MutuallyExclusive (ref) false Configuration object if this is a mutually exclusive checkbox list
dontWrap boolean false Prevents the checkboxes from being wrapped in a fieldset component
legendIsQuestionTitle boolean false Creates a h1 inside the legend (further information)
open boolean false Whether the ‘other’ input should be displayed

Checkbox

Name Type Required Description
id string true The id of the checkbox
name string true The name of the checkbox
value string true The value of the checkbox
classes string false Classes to apply to the checkbox
inputClasses string false Classes to apply to the checkbox input
checked boolean false Whether the checkbox should be checked
label Label (ref) true Settings for the checkbox label
other Input (ref) or Select (ref) false Object with settings for other input or select
otherType string false (true if other provided) Can be set to select or input to set what other input you want in a radio
attributes object false HTML attributes (for example data attributes) to add to the checkbox input element
error Error (ref) false Configuration for validation errors
deselectMessage string false For use with mutually exclusive checkboxes. The text the aria-live will read to warn that selecting the exclusive option will clear all other inputs errors
{% from "components/question/_macro.njk" import onsQuestion %}
{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{% call onsQuestion({
    "title": "How would you like us to contact you?",
    "legendIsQuestionTitle": true
}) %}
    {{
        onsCheckboxes({
            "checkboxesLabel": "Select all that apply",
            "dontWrap": true,
            "name": "contact",
            "checkboxes": [
                {
                    "id": "post",
                    "label": {
                        "text": "By post"
                    },
                    "value": "post"
                },
                {
                    "id": "email",
                    "label": {
                        "text": "By email"
                    },
                    "value": "email"
                },
                {
                    "id": "phone",
                    "label": {
                        "text": "By phone"
                    },
                    "value": "phone",
                    "other": {
                        "otherType": "select",
                        "id": "phone-time",
                        "name": "phone-time",
                        "label": {
                            "text": "Choose preferred time of day"
                        },
                        "options": [
                            {
                                "value": "",
                                "text": "Select an option",
                                "disabled": true,
                                "selected": true
                            },
                            {
                                "value": "anytime",
                                "text": "Anytime of day"
                            },
                            {
                                "value": "morning",
                                "text": "Morning"
                            },
                            {
                                "value": "afternoon",
                                "text": "Afternoon"
                            },
                            {
                                "value": "evening",
                                "text": "Evening"
                            }
                        ]
                    }
                }
            ]
        })
    }}
{% endcall %}

{% macro onsCheckboxes(params) %}
    {% from "components/fieldset/_macro.njk" import onsFieldset %}
    {% from "components/mutually-exclusive/_macro.njk" import onsMutuallyExclusive %}
    {% from "components/checkboxes/_checkbox-macro.njk" import onsCheckbox %}
    {% set fields %}
        <p class="checkboxes__label">{{ params.checkboxesLabel }}</p>
        <div class="checkboxes__items">
            {% for checkbox in params.checkboxes %}
                {% set labelHTML = checkbox.label.text %}
                {% if params.mutuallyExclusive is defined and params.mutuallyExclusive %}
                    {% set exclusiveClass = ' js-exclusive-group-item' %}
                {% endif %}
                <p class="checkboxes__item">
                    {% set config = {
                        "id": checkbox.id,
                        "name": checkbox.name,
                        "value": checkbox.value,
                        "checked": checkbox.checked,
                        "classes": checkbox.classes,
                        "inputClasses": exclusiveClass,
                        "label": {
                            "for": checkbox.id,
                            "text": labelHTML,
                            "description": checkbox.label.description,
                            "classes": checkbox.label.classes | default('')
                        },
                        "attributes": checkbox.attributes
                    } %}
                    {% if checkbox.other is defined and checkbox.other %}
                        {% set config = config | setAttributes({
                            "other": {
                                "open": checkbox.other.open | default(false),
                                "id": checkbox.other.id,
                                "name": checkbox.other.name,
                                "type": checkbox.other.type,
                                "otherType": checkbox.other.otherType,
                                "options": checkbox.other.options,
                                "classes": checkbox.other.classes | default('') + exclusiveClass | default(''),
                                "attributes": checkbox.other.attributes,
                                "label": {
                                    "text": checkbox.other.label.text
                                },
                                "value": checkbox.other.value
                            }
                        }) %}
                    {% endif %}
                    {{ onsCheckbox(config) }}
                </p>
                {% if not loop.last %}
                    <br>
                {% endif %}
            {% endfor %}
        </div>
    {% endset %}
    {% if params.mutuallyExclusive is defined and params.mutuallyExclusive %}
        {% call onsMutuallyExclusive({
            "id": params.id,
            "description": params.description,
            "classes": params.classes,
            "legend": params.legend,
            "legendClasses": params.legendClasses,
            "description": params.description,
            "attributes": params.attributes,
            "dontWrap": params.dontWrap,
            "legendIsQuestionTitle": params.legendIsQuestionTitle,
            "checkbox": params.mutuallyExclusive.checkbox,
            "or": params.mutuallyExclusive.or,
            "deselectMessage": params.mutuallyExclusive.deselectMessage,
            "deselectGroupAdjective": params.mutuallyExclusive.deselectGroupAdjective,
            "deselectCheckboxAdjective": params.mutuallyExclusive.deselectCheckboxAdjective,
            "error": params.error
        }) %}
            {{ fields | safe }}
        {% endcall %}
    {% else %}
        {% call onsFieldset({
            "id": params.id,
            "description": params.description,
            "classes": params.classes,
            "legend": params.legend,
            "legendClasses": params.legendClasses,
            "legendIsQuestionTitle": params.legendIsQuestionTitle,
            "description": params.description,
            "attributes": params.attributes,
            "dontWrap": params.dontWrap,
            "error": params.error
        }) %}
            {{ fields | safe }}
        {% endcall %}
    {% endif %}
{% endmacro %}

$checkbox-input-width: 22px;
$checkbox-padding: 11px;
.checkbox {
  display: inline-block;
  position: relative;
  width: 100%;
  z-index: 1;
  &__input {
    appearance: none;
    background: url(#{$static}/img/icons--check.svg) no-repeat center center;
    background-color: $color-white;
    background-size: 0;
    border: 2px solid $color-input;
    border-radius: 0.2rem;
    box-sizing: border-box;
    height: $checkbox-input-width;
    left: $checkbox-padding;
    position: absolute;
    top: $checkbox-padding + 3px;
    width: $checkbox-input-width;
    z-index: 1;
    &:focus,
    &:checked {
      outline: none;
    }
    &:checked {
      background-size: 14px;
    }
  }
  &__label {
    cursor: pointer;
    display: block;
    padding: $checkbox-padding 1rem $checkbox-padding ($checkbox-padding * 2 + $checkbox-input-width);
    width: 100%;
    &--with-description {
      padding: 0 1rem $checkbox-padding 0;
    }
    .label__description {
      margin-left: -1.75rem;
    }
    &::before {
      background: $color-white;
      border: 1px solid $color-input;
      border-radius: 3px;
      bottom: 0;
      content: '';
      left: 0;
      position: absolute;
      right: 0;
      top: 0;
      z-index: -1;
    }
    * {
      pointer-events: none;
    }
  }
  &__description {
    display: block;
    margin-top: 0.25rem;
  }
  &__other {
    display: block;
    padding: 0 $checkbox-padding $checkbox-padding;
  }
  &__input:checked + &__label::before {
    background: $color-grey-5;
    box-shadow: 0 0 0 1px $color-input;
  }
  .panel--error .radio__input:checked ~ &__other > .input--text:required:not(:focus) {
    border: 1px solid $color-ruby-red;
    outline: 1px solid $color-ruby-red;
    outline-offset: -2px;
  }
  &__input:focus + &__label::before {
    @extend .input:focus;
  }
  &__input:not(:checked) ~ &__other {
    display: none;
  }
  &__input:not(:checked) ~ &__other--open {
    display: block;
  }
  &--toggle & {
    &__input {
      left: 0;
      top: 0.1rem;
      &:focus {
        box-shadow: 0 0 0 3px $color-focus;
      }
    }
    &__label {
      padding: 0 0 0 ($checkbox-input-width + $checkbox-padding);
      &::before {
        background: none;
        border: 0;
      }
    }
    &__input:checked + .checkbox__label::before,
    &__input:focus + .checkbox__label::before {
      background: transparent;
      box-shadow: none;
    }
    &__input:focus + .checkbox__label::before {
      border: 0;
      outline: none;
    }
  }
}
.checkboxes {
  &__label {
    display: block;
    margin: 0 0 0.5rem;
  }
  &__items {
    display: block;
  }
  &__item {
    display: inline-block;
    margin: 0 0 0.5rem;
    width: 100%;
    &:last-child {
      margin-bottom: 0;
    }
    @include mq(s) {
      min-width: 20rem;
      width: auto;
    }
  }
  &--mutually-exclusive__item {
    @extend .checkboxes__item;
    margin-bottom: 0;
  }
}

How to validate checkboxes

To help users make a selection on the page and provide extra detail if it is required, you should:

  • check they have selected at least one checkbox
  • check they have entered something or selected a drop-down option if more detail is required for one of the checkboxes
  • show an error message if they have not selected any of the checkboxes or given any more detail when required

Error messages

Use the correct errors pattern and show the error details above the checkbox options.

<div class="panel panel--error panel--no-title u-mb-s" id="dietary-error">
  <span class="u-vh">Error: </span>
  <div class="panel__body">
    <p class="panel__error">
      <strong>Enter your dietary requirements</strong>
    </p>
    <fieldset class="fieldset">
      <legend class="fieldset__legend">
      </legend>
      <p class="checkboxes__label">Select all that apply</p>
      <div class="checkboxes__items">
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="gluten-free" class="checkbox__input js-checkbox " value="gluten-free">
            <label class="checkbox__label  " for="gluten-free" id="gluten-free-label">Gluten free
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="lactose-intolerant" class="checkbox__input js-checkbox " value="lactose-intolerant">
            <label class="checkbox__label  " for="lactose-intolerant" id="lactose-intolerant-label">Lactose intolerant
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="vegan" class="checkbox__input js-checkbox " value="vegan">
            <label class="checkbox__label  " for="vegan" id="vegan-label">Vegan
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="vegetarian" class="checkbox__input js-checkbox " value="vegetarian">
            <label class="checkbox__label  " for="vegetarian" id="vegetarian-label">Vegetarian
            </label>
          </span>
        </p>
        <br>
        <p class="checkboxes__item">
          <span class="checkbox ">
            <input type="checkbox" id="other-checkbox" class="checkbox__input js-checkbox " value="other" checked aria-controls="other-checkbox-other-wrap" aria-haspopup="true">
            <label class="checkbox__label  " for="other-checkbox" id="other-checkbox-label">Other
            </label>
            <span class="checkbox__other" id="other-checkbox-other-wrap">
              <label class="label u-fs-s--b " for="other-textbox" id="other-textbox-label">Enter dietary requirements
              </label>
              <input type="text" id="other-textbox" class="input input--text input-type__input input--w-auto " name="other-answer" />
            </span>
          </span>
        </p>
      </div>
    </fieldset>
  </div>
</div>
Nunjucks macro options
Name Type Required Description
id string false Id to apply to the fieldset
classes string false Classes to apply to the fieldset
legend string false The legend to apply to the fieldset
legendClasses string false Classes to apply to the legend
name string true The name to apply to the checkboxes
checkboxes Array<Checkbox> true An array of checkboxes to render
mutuallyExclusive MutuallyExclusive (ref) false Configuration object if this is a mutually exclusive checkbox list
dontWrap boolean false Prevents the checkboxes from being wrapped in a fieldset component
legendIsQuestionTitle boolean false Creates a h1 inside the legend (further information)
open boolean false Whether the ‘other’ input should be displayed

Checkbox

Name Type Required Description
id string true The id of the checkbox
name string true The name of the checkbox
value string true The value of the checkbox
classes string false Classes to apply to the checkbox
inputClasses string false Classes to apply to the checkbox input
checked boolean false Whether the checkbox should be checked
label Label (ref) true Settings for the checkbox label
other Input (ref) or Select (ref) false Object with settings for other input or select
otherType string false (true if other provided) Can be set to select or input to set what other input you want in a radio
attributes object false HTML attributes (for example data attributes) to add to the checkbox input element
error Error (ref) false Configuration for validation errors
deselectMessage string false For use with mutually exclusive checkboxes. The text the aria-live will read to warn that selecting the exclusive option will clear all other inputs errors

{% from "components/checkboxes/_macro.njk" import onsCheckboxes %}
{{
    onsCheckboxes({
        "checkboxesLabel": "Select all that apply",
        "name": "dietary",
        "checkboxes": [
            {
                "id": "gluten-free",
                "label": {
                    "text": "Gluten free"
                },
                "value": "gluten-free"
            },
            {
                "id": "lactose-intolerant",
                "label": {
                    "text": "Lactose intolerant"
                },
                "value": "lactose-intolerant"
            },
            {
                "id": "vegan",
                "label": {
                    "text": "Vegan"
                },
                "value": "vegan"
            },
            {
                "id": "vegetarian",
                "label": {
                    "text": "Vegetarian"
                },
                "value": "vegetarian"
            },
            {
                "id": "other-checkbox",
                "label": {
                    "text": "Other"
                },
                "checked": true,
                "value": "other",
                "other": {
                    "id": "other-textbox",
                    "name": "other-answer",
                    "label": {
                        "text": "Enter dietary requirements"
                    }
                }
            }
        ],
        "error": {
            "id": "dietary-error",
            "text": "Enter your dietary requirements",
            "dsExample": isPatternLib
        }
    })
}}

{% macro onsCheckboxes(params) %}
    {% from "components/fieldset/_macro.njk" import onsFieldset %}
    {% from "components/mutually-exclusive/_macro.njk" import onsMutuallyExclusive %}
    {% from "components/checkboxes/_checkbox-macro.njk" import onsCheckbox %}
    {% set fields %}
        <p class="checkboxes__label">{{ params.checkboxesLabel }}</p>
        <div class="checkboxes__items">
            {% for checkbox in params.checkboxes %}
                {% set labelHTML = checkbox.label.text %}
                {% if params.mutuallyExclusive is defined and params.mutuallyExclusive %}
                    {% set exclusiveClass = ' js-exclusive-group-item' %}
                {% endif %}
                <p class="checkboxes__item">
                    {% set config = {
                        "id": checkbox.id,
                        "name": checkbox.name,
                        "value": checkbox.value,
                        "checked": checkbox.checked,
                        "classes": checkbox.classes,
                        "inputClasses": exclusiveClass,
                        "label": {
                            "for": checkbox.id,
                            "text": labelHTML,
                            "description": checkbox.label.description,
                            "classes": checkbox.label.classes | default('')
                        },
                        "attributes": checkbox.attributes
                    } %}
                    {% if checkbox.other is defined and checkbox.other %}
                        {% set config = config | setAttributes({
                            "other": {
                                "open": checkbox.other.open | default(false),
                                "id": checkbox.other.id,
                                "name": checkbox.other.name,
                                "type": checkbox.other.type,
                                "otherType": checkbox.other.otherType,
                                "options": checkbox.other.options,
                                "classes": checkbox.other.classes | default('') + exclusiveClass | default(''),
                                "attributes": checkbox.other.attributes,
                                "label": {
                                    "text": checkbox.other.label.text
                                },
                                "value": checkbox.other.value
                            }
                        }) %}
                    {% endif %}
                    {{ onsCheckbox(config) }}
                </p>
                {% if not loop.last %}
                    <br>
                {% endif %}
            {% endfor %}
        </div>
    {% endset %}
    {% if params.mutuallyExclusive is defined and params.mutuallyExclusive %}
        {% call onsMutuallyExclusive({
            "id": params.id,
            "description": params.description,
            "classes": params.classes,
            "legend": params.legend,
            "legendClasses": params.legendClasses,
            "description": params.description,
            "attributes": params.attributes,
            "dontWrap": params.dontWrap,
            "legendIsQuestionTitle": params.legendIsQuestionTitle,
            "checkbox": params.mutuallyExclusive.checkbox,
            "or": params.mutuallyExclusive.or,
            "deselectMessage": params.mutuallyExclusive.deselectMessage,
            "deselectGroupAdjective": params.mutuallyExclusive.deselectGroupAdjective,
            "deselectCheckboxAdjective": params.mutuallyExclusive.deselectCheckboxAdjective,
            "error": params.error
        }) %}
            {{ fields | safe }}
        {% endcall %}
    {% else %}
        {% call onsFieldset({
            "id": params.id,
            "description": params.description,
            "classes": params.classes,
            "legend": params.legend,
            "legendClasses": params.legendClasses,
            "legendIsQuestionTitle": params.legendIsQuestionTitle,
            "description": params.description,
            "attributes": params.attributes,
            "dontWrap": params.dontWrap,
            "error": params.error
        }) %}
            {{ fields | safe }}
        {% endcall %}
    {% endif %}
{% endmacro %}

$checkbox-input-width: 22px;
$checkbox-padding: 11px;
.checkbox {
  display: inline-block;
  position: relative;
  width: 100%;
  z-index: 1;
  &__input {
    appearance: none;
    background: url(#{$static}/img/icons--check.svg) no-repeat center center;
    background-color: $color-white;
    background-size: 0;
    border: 2px solid $color-input;
    border-radius: 0.2rem;
    box-sizing: border-box;
    height: $checkbox-input-width;
    left: $checkbox-padding;
    position: absolute;
    top: $checkbox-padding + 3px;
    width: $checkbox-input-width;
    z-index: 1;
    &:focus,
    &:checked {
      outline: none;
    }
    &:checked {
      background-size: 14px;
    }
  }
  &__label {
    cursor: pointer;
    display: block;
    padding: $checkbox-padding 1rem $checkbox-padding ($checkbox-padding * 2 + $checkbox-input-width);
    width: 100%;
    &--with-description {
      padding: 0 1rem $checkbox-padding 0;
    }
    .label__description {
      margin-left: -1.75rem;
    }
    &::before {
      background: $color-white;
      border: 1px solid $color-input;
      border-radius: 3px;
      bottom: 0;
      content: '';
      left: 0;
      position: absolute;
      right: 0;
      top: 0;
      z-index: -1;
    }
    * {
      pointer-events: none;
    }
  }
  &__description {
    display: block;
    margin-top: 0.25rem;
  }
  &__other {
    display: block;
    padding: 0 $checkbox-padding $checkbox-padding;
  }
  &__input:checked + &__label::before {
    background: $color-grey-5;
    box-shadow: 0 0 0 1px $color-input;
  }
  .panel--error .radio__input:checked ~ &__other > .input--text:required:not(:focus) {
    border: 1px solid $color-ruby-red;
    outline: 1px solid $color-ruby-red;
    outline-offset: -2px;
  }
  &__input:focus + &__label::before {
    @extend .input:focus;
  }
  &__input:not(:checked) ~ &__other {
    display: none;
  }
  &__input:not(:checked) ~ &__other--open {
    display: block;
  }
  &--toggle & {
    &__input {
      left: 0;
      top: 0.1rem;
      &:focus {
        box-shadow: 0 0 0 3px $color-focus;
      }
    }
    &__label {
      padding: 0 0 0 ($checkbox-input-width + $checkbox-padding);
      &::before {
        background: none;
        border: 0;
      }
    }
    &__input:checked + .checkbox__label::before,
    &__input:focus + .checkbox__label::before {
      background: transparent;
      box-shadow: none;
    }
    &__input:focus + .checkbox__label::before {
      border: 0;
      outline: none;
    }
  }
}
.checkboxes {
  &__label {
    display: block;
    margin: 0 0 0.5rem;
  }
  &__items {
    display: block;
  }
  &__item {
    display: inline-block;
    margin: 0 0 0.5rem;
    width: 100%;
    &:last-child {
      margin-bottom: 0;
    }
    @include mq(s) {
      min-width: 20rem;
      width: auto;
    }
  }
  &--mutually-exclusive__item {
    @extend .checkboxes__item;
    margin-bottom: 0;
  }
}

If no checkbox options have been selected

Use “Select [whatever it is]”.
For example, “Select your dietary requirements”.

If “checkbox with input” is selected but the input field is empty

Use “Enter your [whatever it is]”.
For example, “Enter your sexual orientation”.

If “checkbox with drop-down” is selected but a drop-down option has not been selected

Use “Select [whatever topic the drop-down is asking for]”.
For example, “Select the time of day you would like us to contact you”.

Help improve this component

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

Discuss the ‘Checkboxes’ component on GitHub