1. Government Frontend Component Guide
  2. Form checkboxes

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.

Search for usage of this component on GitHub

How it looks (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

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"
    }
  ]
} %>

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)

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"
    }
  ]
} %>

Checkboxes with data attributes (preview)

Data attributes such as tracking can be applied if required. This will fire tracking identical tracking events on check and uncheck. See below to send different events on uncheck.

<%= render "govuk_publishing_components/components/checkboxes", {
  name: "With tracking",
  items: [
    {
      label: "Tracked",
      value: "tracked",
      data_attributes: {
        track_category: "checkboxClicked",
        track_label: "/news-and-communications",
        track_action: "news",
        track_options: {
          dimension28: 2,
          dimension29: "Tracked"
        },
        controls: null
      }
    }
  ]
} %>

Checkboxes with data attributes and custom uncheck event category (preview)

It can send a different tracking event category for an uncheck. This is handled automatically

<%= render "govuk_publishing_components/components/checkboxes", {
  name: "With tracking and a custom uncheck category",
  items: [
    {
      label: "Tracked",
      value: "tracked",
      data_attributes: {
        track_category: "checkboxClicked",
        untrack_category: "checkboxUnchecked",
        track_label: "/news-and-communications",
        track_action: "news",
        track_options: {
          dimension28: 2,
          dimension29: "Tracked"
        },
        controls: null
      }
    }
  ]
} %>

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 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.
  • See no styling.
<%= 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\">Email address</label><input class=\"govuk-input govuk-!-width-one-third\" id=\"contact-by-email\" name=\"contactingme\" type=\"email\"></div>")
    },
    {
      label: "Phone",
      value: "phone",
      conditional: sanitize("<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=\"contactingme\" type=\"tel\"></div>")
    },
    {
      label: "Other",
      value: "other",
      conditional: "See no styling."
    }
  ]
} %>

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"
        }
      ]
    }
  ]
} %>