checkboxes.yaml

params:
- name: describedBy
  type: string
  required: false
  description: One or more element IDs to add to the input `aria-describedby` attribute without a fieldset, used to provide additional descriptive information for screenreader users.
- name: fieldset
  type: object
  required: false
  description: Options for the fieldset component (for example legend).
  isComponent: true
- name: hint
  type: object
  required: false
  description: Options for the hint component (for example text).
  isComponent: true
- name: errorMessage
  type: object
  required: false
  description: Options for the error message component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`.
  isComponent: true
- name: formGroup
  type: object
  required: false
  description: Options for the form-group wrapper.
  params:
  - name: classes
    type: string
    required: false
    description: Classes to add to the form group (for example to show error state for the whole group).
- name: idPrefix
  type: string
  required: false
  description: String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
- name: name
  type: string
  required: true
  description: Name attribute for all checkbox items.
- name: items
  type: array
  required: true
  description: Array of checkbox items objects.
  params:
  - name: text
    type: string
    required: true
    description: If `html` is set, this is not required. Text to use within each checkbox item label. If `html` is provided, the `text` option will be ignored.
  - name: html
    type: string
    required: true
    description: If `text` is set, this is not required. HTML to use within each checkbox item label. If `html` is provided, the `text` option will be ignored.
  - name: id
    type: string
    required: false
    description: Specific ID attribute for the checkbox item. If omitted, then component global `idPrefix` option will be applied.
  - name: name
    type: string
    required: false
    description: Specific name for the checkbox item. If omitted, then component global `name` string will be applied.
  - name: value
    type: string
    required: true
    description: Value for the checkbox input.
  - name: label
    type: object
    required: false
    description: Provide attributes and classes to each checkbox item label.
    isComponent: true
  - name: hint
    type: object
    required: false
    description: Provide hint to each checkbox item.
    isComponent: true
  - name: divider
    type: string
    required: false
    description: Divider text to separate checkbox items, for example the text 'or'.
  - name: checked
    type: boolean
    required: false
    description: Whether the checkbox should be checked when the page loads. Takes precedence over the top-level `values` option.
  - name: conditional
    type: boolean
    required: false
    description: If `true`, content provided will be revealed when the item is checked.
  - name: conditional.html
    type: string
    required: false
    description: Provide content for the conditional reveal.
  - name: behaviour
    type: string
    required: false
    description: If set to `exclusive`, implements a 'None of these' type behaviour via JavaScript when checkboxes are clicked.
  - name: disabled
    type: boolean
    required: false
    description: If `true`, checkbox will be disabled.
  - name: attributes
    type: object
    required: false
    description: HTML attributes (for example data attributes) to add to the checkbox input tag.
- name: values
  type: array
  required: false
  description: Array of values for checkboxes which should be checked when the page loads. Use this as an alternative to setting the `checked` option on each individual item.
- name: classes
  type: string
  required: false
  description: Classes to add to the checkboxes container.
- name: attributes
  type: object
  required: false
  description: HTML attributes (for example data attributes) to add to the anchor tag.

accessibilityCriteria: |
  ## Conditional reveals
  Must:
  - be visible as static content if JavaScript is unavailable or fails
  - be hidden if JavaScript is available and is collapsed
  - indicate if content is expanded or collapsed
  - indicate that there is collapsed content to interact with

  Note that we have known issues against this criteria: https://github.com/alphagov/govuk_elements/issues/575

examples:
- name: default
  data:
    name: nationality
    items:
      - value: british
        text: British
      - value: irish
        text: Irish
      - value: other
        text: Citizen of another country

- name: with pre-checked values
  data:
    name: nationality
    items:
      - value: british
        text: British
      - value: irish
        text: Irish
      - value: other
        text: Citizen of another country
        conditional:
          html: |
            <div class="govuk-form-group">
              <label class="govuk-label" for="input-example">
                Country
              </label>
            <input class="govuk-input" id="other-country" name="other-country" type="text" value="Ravka">
            </div>
    values: 
      - british
      - other

- name: with divider and None
  data:
    name: with-divider-and-none
    fieldset:
      legend:
        text: Which types of waste do you transport regularly?
        classes: govuk-fieldset__legend--l
        isPageHeading: true
    items:
      - value: animal
        text: Waste from animal carcasses
      - value: mines
        text: Waste from mines or quarries
      - value: farm
        text: Farm or agricultural waste
      - divider: or
      - value: none
        text: None of these
        behaviour: exclusive

- name: with divider, None and conditional items
  data:
    name: with-divider-and-none-and-conditional-items
    fieldset:
      legend:
        text: Do you have any access needs?
        classes: govuk-fieldset__legend--l
        isPageHeading: true
    items:
      - value: accessible-toilets
        text: Accessible toilets available
      - value: braille
        text: Braille translation service available
      - value: disabled-car-parking
        text: Disabled car parking available
      - value: another-access-need
        text: Another access need
        conditional:
          html: |
            <label class="govuk-label" for="other-access-needs">Other access needs</label>
            <textarea class="govuk-textarea govuk-!-width-one-third" name="other-access-needs" id="other-access-needs"></textarea>
      - divider: or
      - value: none
        text: None of these
        behaviour: exclusive

- name: with id and name
  data:
    name: with-id-and-name
    fieldset:
      legend:
        text: What is your nationality?
    hint:
      text: If you have dual nationality, select all options that are relevant to you.
    items:
      - name: british
        id: item_british
        value: yes
        text: British
      - name: irish
        id: item_irish
        value: irish
        text: Irish
      - name: custom-name-scottish
        text: Scottish
        value: scottish

- name: with hints on items
  data:
    name: with-hints-on-items
    fieldset:
      legend:
        text: How do you want to sign in?
        classes: govuk-fieldset__legend--l
        isPageHeading: true
    items:
      - name: gateway
        id: government-gateway
        value: gov-gateway
        text: Sign in with Government Gateway
        hint:
          text: You'll have a user ID if you've registered for Self Assessment or filed a tax return online before.
      - name: verify
        id: govuk-verify
        value: gov-verify
        text: Sign in with GOV.UK Verify
        hint:
          text: You'll have an account if you've already proved your identity with either Barclays, CitizenSafe, Digidentity, Experian, Post Office, Royal Mail or SecureIdentity.

- name: with disabled item
  data:
    name: sign-in
    fieldset:
      legend:
        text: How do you want to sign in?
        classes: govuk-fieldset__legend--l
        isPageHeading: true
    items:
      - name: gateway
        id: government-gateway
        value: gov-gateway
        text: Sign in with Government Gateway
        hint:
          text: You'll have a user ID if you've registered for Self Assessment or filed a tax return online before.
      - name: verify
        id: govuk-verify
        value: gov-verify
        text: Sign in with GOV.UK Verify
        hint:
          text: You'll have an account if you've already proved your identity with either Barclays, CitizenSafe, Digidentity, Experian, Post Office, Royal Mail or SecureIdentity.
        disabled: true

- name: with legend as a page heading
  data:
    name: waste
    fieldset:
      legend:
        text: Which types of waste do you transport regularly?
        classes: govuk-fieldset__legend--l
        isPageHeading: true
    hint:
      text: Select all that apply
    items:
      - value: animal
        text: Waste from animal carcasses
      - value: mines
        text: Waste from mines or quarries
      - value: farm
        text: Farm or agricultural waste

- name: with a medium legend
  data:
    name: waste
    fieldset:
      legend:
        text: Which types of waste do you transport regularly?
        classes: govuk-fieldset__legend--m
    hint:
      text: Select all that apply
    errorMessage:
      text: Select which types of waste you transport regularly
    items:
      - value: animal
        text: Waste from animal carcasses
      - value: mines
        text: Waste from mines or quarries
      - value: farm
        text: Farm or agricultural waste

- name: without fieldset
  data:
    name: colours
    items:
      - value: red
        text: Red
      - value: green
        text: Green
      - value: blue
        text: Blue

- name: with single option set 'aria-describedby' on input
  data:
    name: t-and-c
    errorMessage:
      text: Please accept the terms and conditions
    items:
      - value: yes
        text: I agree to the terms and conditions

- name: with single option (and hint) set 'aria-describedby' on input
  data:
    name: t-and-c-with-hint
    errorMessage:
      text: Please accept the terms and conditions
    items:
      - value: yes
        text: I agree to the terms and conditions
        hint:
          text: Go on, you know you want to!

- name: with fieldset and error message
  data:
    name: nationality
    errorMessage:
      text: Please accept the terms and conditions
    fieldset:
      legend:
        text: What is your nationality?
    items:
      - value: british
        text: British
      - value: irish
        text: Irish
      - value: other
        text: Citizen of another country

- name: with error message
  data:
    name: waste
    errorMessage:
      text: Please select an option
    fieldset:
      legend:
        text: Which types of waste do you transport regularly?
    items:
      - value: animal
        text: Waste from animal carcasses
      - value: mines
        text: Waste from mines or quarries
      - value: farm
        text: Farm or agricultural waste

- name: with error message and hints on items
  data:
    name: waste
    errorMessage:
      text: Please select an option
    fieldset:
      legend:
        text: Which types of waste do you transport regularly?
    items:
      - value: animal
        text: Waste from animal carcasses
        hint:
          text: Nullam id dolor id nibh ultricies vehicula ut id elit.
      - value: mines
        text: Waste from mines or quarries
        hint:
          text: Nullam id dolor id nibh ultricies vehicula ut id elit.
      - value: farm
        text: Farm or agricultural waste
        hint:
          text: Nullam id dolor id nibh ultricies vehicula ut id elit.

- name: with very long option text
  data:
    name: waste
    hint:
      text:
        Nullam id dolor id nibh ultricies vehicula ut id elit.
    errorMessage:
      text:
        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    fieldset:
      legend:
        text:
          Maecenas faucibus mollis interdum?
    items:
      - value: nullam
        text:
          Nullam id dolor id nibh ultricies vehicula ut id elit. Aenean eu leo
          quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.
          Maecenas faucibus mollis interdum. Donec id elit non mi porta gravida
          at eget metus.
      - value: aenean
        text:
          Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis
          vestibulum. Donec sed odio dui. Duis mollis, est non commodo luctus,
          nisi erat porttitor ligula, eget lacinia odio sem nec elit. Cum sociis
          natoque penatibus et magnis dis parturient montes, nascetur ridiculus
          mus. Aenean eu leo quam. Pellentesque ornare sem lacinia quam
          venenatis vestibulum. Cras mattis consectetur purus sit amet
          fermentum.
      - value: fusce
        text:
          Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum
          nibh, ut fermentum massa justo sit amet risus. Etiam porta sem
          malesuada magna mollis euismod. Praesent commodo cursus magna, vel
          scelerisque nisl consectetur et. Etiam porta sem malesuada magna
          mollis euismod. Etiam porta sem malesuada magna mollis euismod.
          Donec sed odio dui. Sed posuere consectetur est at lobortis.

- name: with conditional items
  data:
    name: with-conditional-items
    idPrefix: how-contacted
    fieldset:
      legend:
        text: How do you want to be contacted?
    items:
      - value: email
        text: Email
        conditional:
          html: |
            <label class="govuk-label" for="context-email">Email address</label>
            <input class="govuk-input govuk-!-width-one-third" name="context-email" type="text" id="context-email">
      - value: phone
        text: Phone
        conditional:
          html: |
            <label class="govuk-label" for="contact-phone">Phone number</label>
            <input class="govuk-input govuk-!-width-one-third" name="contact-phone" type="text" id="contact-phone">
      - value: text
        text: Text message
        conditional:
          html: |
            <label class="govuk-label" for="contact-text-message">Mobile phone number</label>
            <input class="govuk-input govuk-!-width-one-third" name="contact-text-message" type="text" id="contact-text-message">

- name: with conditional items with special characters
  data:
    name: contact-prefs
    idPrefix: user.profile[contact-prefs]
    fieldset:
      legend:
        text: How do you want to be contacted?
    items:
      - value: email
        text: Email
        conditional:
          html: |
            <label class="govuk-label" for="context-email">Email address</label>
            <input class="govuk-input govuk-!-width-one-third" name="context-email" type="text" id="context-email">
      - value: phone
        text: Phone
        conditional:
          html: |
            <label class="govuk-label" for="contact-phone">Phone number</label>
            <input class="govuk-input govuk-!-width-one-third" name="contact-phone" type="text" id="contact-phone">
      - value: text
        text: Text message
        conditional:
          html: |
            <label class="govuk-label" for="contact-text-message">Mobile phone number</label>
            <input class="govuk-input govuk-!-width-one-third" name="contact-text-message" type="text" id="contact-text-message">

- name: with conditional item checked
  data:
    name: how-contacted-checked
    idPrefix: how-contacted-checked
    fieldset:
      legend:
        text: How do you want to be contacted?
    items:
    - value: email
      text: Email
      checked: true
      conditional:
        html: |
          <label class="govuk-label" for="context-email">Email address</label>
          <input class="govuk-input govuk-!-width-one-third" name="context-email" type="text" id="context-email">
    - value: phone
      text: Phone
      conditional:
        html: |
          <label class="govuk-label" for="contact-phone">Phone number</label>
          <input class="govuk-input govuk-!-width-one-third" name="contact-phone" type="text" id="contact-phone">
    - value: text
      text: Text message
      conditional:
        html: |
          <label class="govuk-label" for="contact-text-message">Mobile phone number</label>
          <input class="govuk-input govuk-!-width-one-third" name="contact-text-message" type="text" id="contact-text-message">

- name: with optional form-group classes showing group error
  data:
    name: how-contacted-checked
    idPrefix: how-contacted-checked
    formGroup:
      classes: 'govuk-form-group--error'
    fieldset:
      legend:
        text: How do you want to be contacted?
    items:
    - value: email
      text: Email
      conditional:
        html: |
          <label class="govuk-label" for="context-email">Email address</label>
          <input class="govuk-input govuk-!-width-one-third" name="context-email" type="text" id="context-email">
    - value: phone
      text: Phone
      checked: true
      conditional:
        html: |
          <label class="govuk-label" for="contact-phone">Phone number</label>
          <span id="contact-phone-error" class="govuk-error-message">Problem with input</span>
          <input class="govuk-input govuk-input--error govuk-!-width-one-third" name="contact-phone" type="text" id="contact-phone" aria-describedby="contact-phone-error">
    - value: text
      text: Text message
      conditional:
        html: |
          <label class="govuk-label" for="contact-text-message">Mobile phone number</label>
          <input class="govuk-input govuk-!-width-one-third" name="contact-text-message" type="text" id="contact-text-message">

- name: small
  data:
    idPrefix: nationality
    name: nationality
    classes: govuk-checkboxes--small
    fieldset:
      legend:
        text: Filter by
    items:
      - value: a
        text: a thing
      - value: b
        text: another thing
      - value: c
        text: this thing

- name: small with long text
  data:
    idPrefix: nationality
    name: nationality
    classes: govuk-checkboxes--small
    fieldset:
      legend:
        text: Filter by
    items:
      - value: nullam
        text:
          Nullam id dolor id nibh ultricies vehicula ut id elit. Aenean eu leo
          quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.
          Maecenas faucibus mollis interdum. Donec id elit non mi porta gravida
          at eget metus.
      - value: aenean
        text:
          Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis
          vestibulum. Donec sed odio dui. Duis mollis, est non commodo luctus,
          nisi erat porttitor ligula, eget lacinia odio sem nec elit. Cum sociis
          natoque penatibus et magnis dis parturient montes, nascetur ridiculus
          mus. Aenean eu leo quam. Pellentesque ornare sem lacinia quam
          venenatis vestibulum. Cras mattis consectetur purus sit amet
          fermentum.
      - value: fusce
        text:
          Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum
          nibh, ut fermentum massa justo sit amet risus. Etiam porta sem
          malesuada magna mollis euismod. Praesent commodo cursus magna, vel
          scelerisque nisl consectetur et. Etiam porta sem malesuada magna
          mollis euismod. Etiam porta sem malesuada magna mollis euismod.
          Donec sed odio dui. Sed posuere consectetur est at lobortis.

- name: small with error
  data:
    idPrefix: nationality
    name: nationality
    classes: govuk-checkboxes--small
    errorMessage:
      text: "Select a thing"
    fieldset:
      legend:
        text: Filter by
    items:
      - value: a
        text: a thing
      - value: b
        text: another thing
      - value: c
        text: this thing

- name: small with hint
  data:
    idPrefix: nationality
    name: nationality
    classes: govuk-checkboxes--small
    fieldset:
      legend:
        text: Filter by
    items:
      - value: a
        text: a thing
        hint:
          text: hint for a thing
      - value: b
        text: another thing
      - value: c
        text: this thing

- name: small with disabled
  data:
    idPrefix: nationality
    name: nationality
    classes: govuk-checkboxes--small
    fieldset:
      legend:
        text: Filter by
    items:
      - value: a
        text: a thing
      - value: b
        text: another thing
      - value: c
        text: this thing
        disabled: true

- name: small with conditional reveal
  data:
    name: how-contacted
    idPrefix: how-contacted
    classes: govuk-checkboxes--small
    fieldset:
      legend:
        text: How do you want to be contacted?
    items:
      - value: a
        text: a thing
        conditional:
          html: |
            <label class="govuk-label" for="context-email">Foo</label>
            <input class="govuk-input govuk-!-width-one-third" name="context-email" type="text" id="context-email">
      - value: b
        text: another thing

# Hidden examples are not shown in the review app, but are used for tests and HTML fixtures
- name: with idPrefix
  hidden: true
  data:
    name: example-name
    idPrefix: nationality
    items:
      - value: 1
        text: Option 1
      - value: 2
        text: Option 2
- name: with falsey values
  hidden: true
  data:
    name: example-name
    items:
      - value: 1
        text: Option 1
      - false
      - null
      - ""
      - value: 2
        text: Option 2
- name: classes
  hidden: true
  data:
    name: example-name
    classes: app-checkboxes--custom-modifier
    items:
      - value: 1
        text: Option 1
      - value: 2
        text: Option 2
- name: with fieldset describedBy
  hidden: true
  data:
    name: example-name
    fieldset:
      describedBy: some-id
    items:
      - value: 1
        text: Option 1
      - value: 2
        text: Option 2
    hint:
      text: If you have dual nationality, select all options that are relevant to you.
- name: attributes
  hidden: true
  data:
    name: example-name
    attributes:
      data-attribute: value
      data-second-attribute: second-value
    items:
      - value: 1
        text: Option 1
      - value: 2
        text: Option 2
- name: with checked item
  hidden: true
  data:
    name: example-name
    items:
      - value: 1
        text: Option 1
      - value: 2
        text: Option 2
        checked: true
      - value: 3
        text: Option 3
        checked: true
- name: items with attributes
  hidden: true
  data:
    name: example-name
    items:
      - value: 1
        text: Option 1
        attributes:
          data-attribute: ABC
          data-second-attribute: DEF
      - value: 2
        text: Option 2
        attributes:
          data-attribute: GHI
          data-second-attribute: JKL
- name: empty conditional
  hidden: true
  data:
    name: example-conditional
    items:
      - value: foo
        text: Foo
        conditional:
          html: false
- name: with label classes
  hidden: true
  data:
    name: example-label-classes
    items:
      - value: yes
        text: Yes
        label:
          classes: bold
- name: multiple hints
  hidden: true
  data:
    name: example-multiple-hints
    hint:
      text: If you have dual nationality, select all options that are relevant to you.
    items:
      - value: british
        text: British
        hint:
          text: Hint for british option here
      - value: irish
        text: Irish
      - value: other
        hint:
          text: Hint for other option here
- name: with error message and hint
  hidden: true
  data:
    name: example
    items:
      - value: british
        text: British
      - value: irish
        text: Irish
    errorMessage:
      text: Please select an option
    fieldset:
      legend:
        text: What is your nationality?
    hint:
      text: If you have dual nationality, select all options that are relevant to you.
- name: with error, hint and fieldset describedBy
  hidden: true
  data:
    name: example
    errorMessage:
      text: Please select an option
    fieldset:
      describedBy: some-id
      legend:
        text: What is your nationality?
    hint:
      text: If you have dual nationality, select all options that are relevant to you.
    items:
      - value: british
        text: British
      - value: irish
        text: Irish
- name: label with attributes
  hidden: true
  data:
    name: example-name
    items:
      - value: 1
        html: <b>Option 1</b>
        label:
          attributes:
            data-attribute: value
            data-second-attribute: second-value
- name: fieldset params
  hidden: true
  data:
    name: example-name
    errorMessage:
      text: Please select an option
    fieldset:
      legend:
        text: What is your nationality?
      classes: app-fieldset--custom-modifier
      attributes:
        data-attribute: value
        data-second-attribute: second-value
    items:
      - value: british
        text: British
      - value: irish
        text: Irish
- name: fieldset html params
  hidden: true
  data:
    name: example-name
    fieldset:
      legend:
        html: What is your <b>nationality</b>?
    items:
      - value: british
        text: British
      - value: irish
        text: Irish
- name: with single option set 'aria-describedby' on input, and describedBy
  hidden: true
  data:
    describedBy: some-id
    name: t-and-c
    errorMessage:
      text: Please accept the terms and conditions
    items:
      - value: yes
        text: I agree to the terms and conditions
- name: with single option (and hint) set 'aria-describedby' on input, and describedBy
  hidden: true
  data:
    describedBy: some-id
    name: t-and-c-with-hint
    errorMessage:
      text: Please accept the terms and conditions
    items:
      - value: yes
        text: I agree to the terms and conditions
        hint:
          text: Go on, you know you want to!
- name: with error and idPrefix
  hidden: true
  data:
    name: name-of-checkboxes
    errorMessage:
      text: Please select an option
    idPrefix: id-prefix
    items:
      - value: animal
        text: Waste from animal carcasses
- name: with error message and fieldset describedBy
  hidden: true
  data:
    name: example
    errorMessage:
      text: Please select an option
    fieldset:
      describedBy: some-id
      legend:
        text: What is your nationality?
    items:
      - value: british
        text: British
      - value: irish
        text: Irish

- name: item checked overrides values
  hidden: true
  data:
    name: colors
    items:
      - value: red
        text: Red
      - value: green
        text: Green
        checked: false
      - value: blue
        text: Blue
    values: [red, green]