Component

Form checkboxes

Let users select one or more options with checkboxes.

If there is more than one checkbox they are rendered in a list. If there is only one, the markup is simplified to a single div and a heading attribute is not required. A [] needs to be appended to the name for Rails to treat the checkbox value as an array, otherwise only the last selected item is captured.

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

How to call this component

<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_colour_default",
  items: [
    {
      label: "Red",
      value: "red_colour"
    }
  ]
} %>

GOV.UK Design System

This component incorporates components from the GOV.UK Design System:

Accessibility acceptance criteria

The component must:

  • accept focus
  • be focusable with a keyboard
  • be usable with a keyboard
  • be usable with touch
  • indicate when they have focus
  • have correctly associated labels

Labels use the label component.

Other examples

Standard options

This component uses the component wrapper helper. It accepts the following options and applies them to the parent element of the component. See the component wrapper helper documentation for more detail.

  • id - accepts a string for the element ID attribute
  • data_attributes - accepts a hash of data attributes
  • aria - accepts a hash of aria attributes
  • classes - accepts a space separated string of classes, these should not be used for styling and must be prefixed with js-
  • role - accepts a space separated string of roles
  • lang - accepts a language attribute value
  • open - accepts an open attribute value (true or false)
  • hidden - accepts an empty string, ‘hidden’, or ‘until-found’
  • tabindex - accepts an integer. The integer can also be passed as a string.
  • dir - accepts ‘rtl’, ‘ltr’, or ‘auto’.

With multiple checkboxes (preview)

When more than one checkbox is shown they are wrapped in a fieldset element, which requires a legend. This must be supplied to the component using the heading option.

What is your favourite colour?
Select all that apply.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_colour[]",
  heading: "What is your favourite colour?",
  items: [
    {
      label: "Red",
      value: "red"
    },
    {
      label: "Green",
      value: "green"
    },
    {
      label: "Blue",
      value: "blue"
    }
  ]
} %>

With small checkboxes (preview)

What is your favourite synonym for small?
Select all that apply.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_small_synonym[]",
  heading: "What is your favourite synonym for small?",
  small: true,
  items: [
    {
      label: "Tiny",
      value: "tiny"
    },
    {
      label: "Little",
      value: "little"
    }
  ]
} %>

With a heading on one checkbox (preview)

One checkbox does not require a fieldset and therefore does not require a legend. However, if a heading is supplied, a fieldset will be included in the component and the heading used as the legend, as shown.

Please tick the box to agree
Select all that apply.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "agree",
  heading: "Please tick the box to agree",
  items: [
    {
      label: "I agree",
      value: "agree"
    }
  ]
} %>

With custom hint text (preview)

Hint text defaults to ‘Select all that apply’ but can be overridden with this option. Note that a hint (and a heading) is only displayed if there is more than one checkbox.

What is your favourite skittle?
Taste the rainbow
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_skittle[]",
  heading: "What is your favourite skittle?",
  hint_text: "Taste the rainbow",
  items: [
    {
      label: "Red",
      value: "red"
    },
    {
      label: "Green",
      value: "green"
    },
    {
      label: "Blue",
      value: "blue"
    }
  ]
} %>

With description text (preview)

If a description text is added, it is displayed under the legend but before the hint text. The description text can only render text and not govspeak specific syntax. This is a pattern that is used across GOV.UK where a question is followed by a description.

Choose your favourite skittles
Skittles consist of hard sugar shells imprinted with the letter "S". The interior consists mainly of sugar, corn syrup, and hydrogenated palm kernel oil along with fruit juice, citric acid, natural and artificial flavors.
Taste the rainbow
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_skittle[]",
  heading: "Choose your favourite skittles",
  description: "Skittles consist of hard sugar shells imprinted with the letter \"S\".
    The interior consists mainly of sugar, corn syrup, and hydrogenated
    palm kernel oil along with fruit juice, citric acid, natural and artificial flavors.
    ",
  hint_text: "Taste the rainbow",
  items: [
    {
      label: "Red",
      value: "red"
    },
    {
      label: "Green",
      value: "green"
    },
    {
      label: "Blue",
      value: "blue"
    }
  ]
} %>

With description text and header (preview)

If a description text is added with a page heading, it is displayed under the heading but before the hint text. The description text can only render text and not govspeak specific syntax. This is a pattern that is used across GOV.UK where a question is followed by a description.

Choose your favourite skittles
Skittles consist of hard sugar shells imprinted with the letter "S". The interior consists mainly of sugar, corn syrup, and hydrogenated palm kernel oil along with fruit juice, citric acid, natural and artificial flavors.
Taste the rainbow
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_skittle[]",
  heading: "Choose your favourite skittles",
  is_page_heading: true,
  description: "Skittles consist of hard sugar shells imprinted with the letter \"S\".
    The interior consists mainly of sugar, corn syrup, and hydrogenated
    palm kernel oil along with fruit juice, citric acid, natural and artificial flavors.
    ",
  hint_text: "Taste the rainbow",
  items: [
    {
      label: "Red",
      value: "red"
    },
    {
      label: "Green",
      value: "green"
    },
    {
      label: "Blue",
      value: "blue"
    }
  ]
} %>

With page header and caption (preview)

If a caption text is provided with a page heading, it will be displayed above the heading. A caption can only be used with a page heading. If a heading is not provided the caption will not render. The pattern is used across GOV.UK to show a high-level section that this page question falls into.

Question 3 of 9

Choose your favourite skittles
Select all that apply.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_skittle[]",
  heading: "Choose your favourite skittles",
  heading_caption: "Question 3 of 9",
  is_page_heading: true,
  items: [
    {
      label: "Red",
      value: "red"
    },
    {
      label: "Green",
      value: "green"
    },
    {
      label: "Blue",
      value: "blue"
    }
  ]
} %>

Without hint text (preview)

Hint text can be removed entirely with this option. Note that this option can be combined with the visually_hide_heading option.

What is your favourite skittle? 
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_skittle[]",
  heading: "What is your favourite skittle?",
  no_hint_text: true,
  items: [
    {
      label: "Mauve",
      value: "mauve"
    },
    {
      label: "Sunset orange",
      value: "sunsetorange"
    }
  ]
} %>

With a hidden heading (preview)

If the heading/legend on the checkboxes is not required, it can be visually hidden using this option. It will still be visible to screen readers.

What is your favourite colour?
Select all that apply.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_colour[]",
  heading: "What is your favourite colour?",
  visually_hide_heading: true,
  items: [
    {
      label: "Red",
      value: "red"
    },
    {
      label: "Green",
      value: "green"
    },
    {
      label: "Blue",
      value: "blue"
    }
  ]
} %>

With a custom id attribute (preview)

Note that if an id is not given one is generated automatically. In either case, the id is applied to the parent element of the checkboxes, and each checkbox is given the same id with an incremented number at the end, e.g. the checkboxes below have ids of potatoes-0 and potatoes-1.

What kind of potatoes do you like?
Select all that apply.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "potatoes[]",
  id: "potatoes",
  heading: "What kind of potatoes do you like?",
  items: [
    {
      label: "Red",
      value: "red"
    },
    {
      label: "Green",
      value: "green"
    }
  ]
} %>

With custom ids on individal checkboxes (preview)

Individual checkboxes can be given specific ids if required. Note that the general id option can still be used, but the individual ids will override the general one if it is given.

What kind of carrots do you like?
Select all that apply.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "carrots[]",
  id: "carrots",
  heading: "What kind of carrots do you like?",
  items: [
    {
      label: "Orange",
      value: "orange",
      id: "custom-orange-id"
    },
    {
      label: "Purple",
      value: "purple"
    }
  ]
} %>

With legend as page heading (preview)

Since the legend/heading is required, if the checkboxes are alone on a page it makes sense to use this element as the H1 on the page rather than duplicate text.

What is your favourite colour?
Select all that apply.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_colour[]",
  heading: "What is your favourite colour?",
  is_page_heading: true,
  items: [
    {
      label: "Red",
      value: "red"
    },
    {
      label: "Green",
      value: "green"
    },
    {
      label: "Blue",
      value: "blue"
    }
  ]
} %>

With custom heading size (preview)

This allows the size of the legend to be changed. Valid options are s, m, l, xl, defaulting to m if no option is passed.

If the is_page_heading option is true and heading_size is not set, the text size will be xl.

What is your favourite colour?
Select all that apply.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_colour[]",
  heading: "What is your favourite colour?",
  heading_size: "s",
  items: [
    {
      label: "Red",
      value: "red"
    },
    {
      label: "Green",
      value: "green"
    },
    {
      label: "Blue",
      value: "blue"
    }
  ]
} %>

With aria controls attributes (preview)

Aria controls attributes are applied to the checkboxes only if JavaScript is enabled.

What areas are you interested in?
Select all that apply.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "aria_controls[]",
  heading: "What areas are you interested in?",
  items: [
    {
      label: "Farming and the environment",
      value: "farming",
      controls: "js-live-results"
    },
    {
      label: "Water recycling",
      value: "water",
      controls: "js-live-results"
    }
  ]
} %>

Checkboxes with individual hints (preview)

What is your nationality?
If you have dual nationality, select all options that are relevant to you.
including English, Scottish, Welsh and Northern Irish
anything other than the above
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "nationality[]",
  heading: "What is your nationality?",
  hint_text: "If you have dual nationality, select all options that are relevant to you.",
  items: [
    {
      label: "British",
      value: "british",
      hint: "including English, Scottish, Welsh and Northern Irish"
    },
    {
      label: "Irish",
      value: "irish"
    },
    {
      label: "Other",
      value: "other",
      hint: "anything other than the above"
    }
  ]
} %>

Checkbox items with error (preview)

What is your nationality?
If you have dual nationality, select all options that are relevant to you.

Select if you are British, Irish or a citizen of a different country

including English, Scottish, Welsh and Northern Irish
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "nationality[]",
  heading: "What is your nationality?",
  error: "Select if you are British, Irish or a citizen of a different country",
  hint_text: "If you have dual nationality, select all options that are relevant to you.",
  items: [
    {
      label: "British",
      value: "british",
      hint: "including English, Scottish, Welsh and Northern Irish"
    },
    {
      label: "Irish",
      value: "irish"
    },
    {
      label: "Other",
      value: "other"
    }
  ]
} %>

Checkbox with exclusive item (preview)

Allows an option to become exclusive, as follows:

  • when the exclusive item is checked, all non-exclusive items are unchecked
  • when a non-exclusive item is checked, the exclusive item is unchecked

This behaviour should be doubled by similar checks on the backend.

What kind of expertise can you offer?
Select the types of support you can offer.
or
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "nationality-exclusive[]",
  heading: "What kind of expertise can you offer?",
  hint_text: "Select the types of support you can offer.",
  items: [
    {
      label: "Medical",
      value: "medical"
    },
    {
      label: "Engineering",
      value: "engineering"
    },
    {
      label: "Other",
      value: "other"
    },
    "or",
    {
      label: "I cannot offer expertise",
      value: "no-expertise",
      exclusive: true
    }
  ]
} %>

Checkbox items with conditional reveal (preview)

Checkboxes can be configured to show additional elements when checked. This could include further components, such as text inputs as shown.

Note that if you do insert HTML, this may cause accessibility violations if the additional elements have different name attributes to the checkboxes. No styling will be applied to the inserted content by the component.

How would you like to be contacted?
Please select all options that are relevant to you.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "contactingme[]",
  id: "contactingme",
  heading: "How would you like to be contacted?",
  hint_text: "Please select all options that are relevant to you.",
  items: [
    {
      label: "Email",
      value: "email",
      conditional: sanitize("<div class=\"govuk-form-group\"><label class=\"govuk-label\" for=\"contact-by-email-0\">Email address</label><input class=\"govuk-input govuk-!-width-one-third\" id=\"contact-by-email-0\" name=\"contactingme\" type=\"email\"></div>")
    },
    {
      label: "Phone",
      value: "phone",
      conditional: sanitize("<div class=\"govuk-form-group\"><label class=\"govuk-label\" for=\"contact-by-phone-0\">Phone number</label><input class=\"govuk-input govuk-!-width-one-third\" id=\"contact-by-phone-0\" name=\"contactingme\" type=\"tel\"></div>")
    },
    {
      label: "Text message",
      value: "text",
      conditional: sanitize("<div class=\"govuk-form-group\"><label class=\"govuk-label\" for=\"contact-by-text-0\">Mobile phone number</label><input class=\"govuk-input govuk-!-width-one-third\" id=\"contact-by-text-0\" name=\"contactingme\" type=\"tel\"></div>")
    }
  ]
} %>

Checkbox items with conditional reveal checked (preview)

How would you like to be contacted?
Please select all options that are relevant to you.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "contacting-checked[]",
  id: "contacting-checked",
  heading: "How would you like to be contacted?",
  hint_text: "Please select all options that are relevant to you.",
  items: [
    {
      label: "Email",
      value: "email",
      conditional: sanitize("<div class=\"govuk-form-group\"><label class=\"govuk-label\" for=\"contact-by-email-1\">Email address</label><input class=\"govuk-input govuk-!-width-one-third\" id=\"contact-by-email-1\" name=\"contactingme\" type=\"email\"></div>"),
      checked: true
    },
    {
      label: "Phone",
      value: "phone",
      conditional: sanitize("<div class=\"govuk-form-group\"><label class=\"govuk-label\" for=\"contact-by-phone-1\">Phone number</label><input class=\"govuk-input govuk-!-width-one-third\" id=\"contact-by-phone-1\" name=\"contactingme\" type=\"tel\"></div>")
    },
    {
      label: "Text message",
      value: "text",
      conditional: sanitize("<div class=\"govuk-form-group\"><label class=\"govuk-label\" for=\"contact-by-text-1\">Mobile phone number</label><input class=\"govuk-input govuk-!-width-one-third\" id=\"contact-by-text-1\" name=\"contactingme\" type=\"tel\"></div>")
    }
  ]
} %>

Checkbox items with checked items (preview)

What is your nationality?
If you have dual nationality, select all options that are relevant to you.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "nationality[]",
  heading: "What is your nationality?",
  hint_text: "If you have dual nationality, select all options that are relevant to you.",
  items: [
    {
      label: "British",
      value: "british",
      checked: true
    },
    {
      label: "Irish",
      value: "irish"
    },
    {
      label: "Other",
      value: "other"
    }
  ]
} %>

Checkbox items with nested checkboxes (preview)

What is your favourite colour?
Select all that apply.
<%= render "govuk_publishing_components/components/checkboxes", {
  name: "favourite_colour[]",
  heading: "What is your favourite colour?",
  items: [
    {
      label: "Red",
      value: "red",
      items: [
        {
          label: "Light Red",
          value: "light_red"
        },
        {
          label: "Dark Red",
          value: "dark_red"
        }
      ]
    },
    {
      label: "Blue",
      value: "blue",
      items: [
        {
          label: "Light blue",
          value: "light_blue"
        },
        {
          label: "Dark blue",
          value: "dark_blue"
        }
      ]
    },
    {
      label: "Other",
      value: "other",
      items: [
        {
          label: "Orange",
          value: "orange"
        },
        {
          label: "Puce",
          value: "puce"
        }
      ]
    }
  ]
} %>