name: Form checkboxes
description: Let users select one or more options by using the checkboxes component.
body: This component uses [Checkbox component](/component-guide/checkbox).
govuk_frontend_components:
  - checkboxes
accessibility_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](/component-guide/label).
examples:
  default:
    data:
      name: "favourite_colour"
      heading: "What is your favourite colour?"
      items:
        - label: "Red"
          value: "red"
        - label: "Green"
          value: "green"
        - label: "Blue"
          value: "blue"
  with_legend_as_page_heading:
    data:
      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"
  custom_hint_text:
    data:
      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"
  checkbox_items_with_hint:
    data:
      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"
  checkbox_items_with_error:
    data:
      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:
    data:
      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"
          conditional: "including English, Scottish, Welsh and Northern Irish"
        - label: "Irish"
          value: "irish"
        - label: "Other"
          value: "other"
  checkbox_items_with_checked_items:
    data:
      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:
    data:
      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"