name: Form radio button
description: A radio button is an element that allows users to answer a question by selecting an option. If you have a question with more than one option you should stack radio buttons.
body: |
  You can also use 'or' as an item to break up radios.

  If JavaScript is disabled a conditionally revealed content expands fully. All of the functionality (including aria attributes) are added using JavaScript.
accessibility_criteria: |
  Radio buttons should

  - accept focus
  - be focusable with a keyboard
  - be usable with a keyboard
  - indicate when they have focus
  - change in appearance when touched (in the touch-down state)
  - be usable with touch
  - have label with a touch area similar to the input
  - be usable with [voice commands](https://www.w3.org/WAI/perspectives/voice.html)
  - have visible text
  - have a meaningful accessible name
  - be usable when interacting with the label
  - additional information in hint text should be read out found when focusing inputs
  - should always be used nested in a fieldset so that it has proper context, useful for users of assistive technologies.

  [Keyboard interaction](https://www.w3.org/TR/wai-aria-practices-1.1/#radiobutton)

  - when a radio group receives focus:
    - if a radio button is checked, focus is set on the checked button.
    - if none of the radio buttons are checked, focus is set on the first radio button in the group.
  - Space: checks the focused radio button if it is not already checked.
  - Right Arrow and Down Arrow: move focus to the next radio button in the group, uncheck the previously focused button, and check the newly focused button. If focus is on the last button, focus moves to the first button.
  - Left Arrow and Up Arrow: move focus to the previous radio button in the group, uncheck the previously focused button, and check the newly focused button. If focus is on the first button, focus moves to the last button.

accessibility_excluded_rules:
  - aria-expanded # We use aria expanded to reflect the state of a conditionally revealed radio content even if this attribute is not officially supported on this element.
govuk_frontend_components:
  - radios
examples:
  default:
    data:
      name: "radio-group"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
  with_small_radios:
    data:
      name: "radio-group"
      small: true
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
  with_bold:
    description: 'Used to provide better contrast between long labels and hint text, Note that the `:or` option [is documented as a string due to a bug](https://github.com/alphagov/govuk_publishing_components/issues/102)'
    data:
      name: "radio-group-bold"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
        hint_text: "You'll have a user ID if you've signed up to do things like sign up Self Assessment tax return online."
        bold: true
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
        hint_text: "You'll have an account if you've already proved your identity with a certified company, such as the Post Office."
        bold: true
  with_bottom_margin:
    description: "The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to a margin bottom of 30px (6)."
    data:
      name: "radio-group"
      margin_bottom: 9
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
  with_hint_on_form_group:
    data:
      name: "radio-group-error"
      id_prefix: "hint"
      hint: "You’ll need to prove your identity using one of the following methods"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
  with_heading:
    description: This adds a legend element containing the text supplied.
    data:
      name: "radio-group-heading"
      heading: "Are you hungry?"
      items:
      - value: "yes"
        text: "Yes"
      - value: "no"
        text: "No"
  with_heading_and_hint:
    data:
      name: "radio-group-heading"
      heading: "What is your favourite colour?"
      hint: "If your favourite is not below, pick the colour closest to it."
      items:
      - value: "red"
        text: "Red"
      - value: "green"
        text: "Green"
      - value: "blue"
        text: "Blue"
  with_page_heading:
    description: This adds a H1 element containing the text supplied.
    data:
      name: "radio-group-heading"
      heading: "Is it raining?"
      is_page_heading: true
      items:
      - value: "yes"
        text: "Yes"
      - value: "no"
        text: "No"
  with_page_header_and_caption:
    description: |
      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.
    data:
      name: "radio-group-heading"
      heading: "Is it snowing?"
      heading_caption: "Question 3 of 9"
      is_page_heading: true
      items:
        - value: "yes"
          text: "Yes"
        - value: "no"
          text: "No"
  with_page_heading_and_hint:
    data:
      name: "radio-group-heading"
      heading: "Is it snowing?"
      is_page_heading: true
      hint: "Sleet or hail doesn’t count."
      items:
      - value: "yes"
        text: "Yes"
      - value: "no"
        text: "No"
  with_description_only:
    data:
      name: "radio-group-description"
      heading: "What is your favourite colour?"
      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.
      items:
      - value: "red"
        text: "Red"
      - value: "green"
        text: "Green"
      - value: "blue"
        text: "Blue"
  with_description_and_hint:
    data:
      name: "radio-group-description"
      heading: "What is your favourite colour?"
      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: "Choose the colour"
      items:
      - value: "red"
        text: "Red"
      - value: "green"
        text: "Green"
      - value: "blue"
        text: "Blue"
  with_description_and_page_heading:
    data:
      name: "radio-group-description"
      heading: "What is your favourite colour?"
      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: "Choose the colour"
      items:
      - value: "red"
        text: "Red"
      - value: "green"
        text: "Green"
      - value: "blue"
        text: "Blue"
  with_custom_heading_size:
    description: |
      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.
    data:
      name: "radio-group-description"
      heading: "What is your favourite colour?"
      heading_size: "s"
      items:
      - value: "red"
        text: "Red"
      - value: "green"
        text: "Green"
      - value: "blue"
        text: "Blue"
  with_custom_heading_level:
    description: This allows the heading level to be changed. Heading level will default to `h2` if nothing is passed.
    data:
      name: "radio-group-description"
      heading: "What is your favourite colour?"
      heading_level: 3
      items:
      - value: "red"
        text: "Red"
      - value: "green"
        text: "Green"
      - value: "blue"
        text: "Blue"
  with_hint_text_on_radios:
    data:
      name: "radio-group-hint-text"
      items:
      - value: "government-gateway"
        hint_text: "You'll have a user ID if you've signed up to do things like sign up Self Assessment tax return online."
        text: "Use Government Gateway"
      - value: "govuk-verify"
        hint_text: "You'll have an account if you've already proved your identity with a certified company, such as the Post Office."
        text: "Use GOV.UK Verify"
  with_checked_option:
    data:
      name: "radio-group-checked"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
        checked: true
  with_data_attributes:
    data:
      name: "radio-group-data-attributes"
      items:
      - value: "cool-button"
        text: "Best button in town"
        data_attributes: { "contextual-guidance": "cool-buttons-guidance" }
      - value: "no-data-attributes-button"
        text: "Worst button in town"
  with_custom_id_prefix:
    data:
      id_prefix: 'custom'
      name: "radio-custom-id-prefix"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
  with_or_divider:
    description: "See [related service manual gudiance for this pattern](https://www.gov.uk/service-manual/design/writing-for-user-interfaces#ask-questions-that-users-can-understand)"
    data:
      name: "radio-group-or-divider"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
      - :or
      - value: "create-an-account"
        text: "Create an account"
  extreme:
    description: 'Note that the `:or` option [is documented as a string due to a bug](https://github.com/alphagov/govuk_publishing_components/issues/102)'
    data:
      id_prefix: 'extreme'
      name: "radio-custom-extreme"
      items:
      - value: "extreme-value-1"
        hint_text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus sapien justo, lobortis elementum tortor in, luctus interdum turpis. Nam sit amet nulla nec arcu condimentum dapibus quis varius metus. Suspendisse cursus tristique diam et vestibulum. Proin nec lacinia tortor. Morbi at nisi id lorem aliquam ullamcorper. Pellentesque laoreet sit amet leo sodales ultricies. Suspendisse maximus efficitur odio in tristique."
        text: "Quisque tincidunt venenatis bibendum. Morbi volutpat magna euismod ipsum consequat cursus. Etiam bibendum interdum ultricies."
        bold: true
      - value: "extreme-value-2"
        hint_text: "Cras mi neque, porttitor mattis ultricies id, fringilla non ipsum. Etiam non elit ac magna tincidunt ultrices. Morbi eu quam sed justo scelerisque efficitur sed ut risus. Integer commodo, lectus et venenatis maximus, augue erat egestas nulla, eget fermentum augue lacus tempor nulla. Aenean ultricies suscipit erat, vitae hendrerit neque varius nec. Etiam ac euismod massa. Ut at erat id sapien mollis posuere."
        text: "Aliquam rutrum lobortis blandit. Praesent sit amet lacinia libero. Morbi nulla tellus, euismod et ipsum id, porta volutpat enim. Ut mauris libero"
        bold: true
      - :or
      - value: "extreme-value-3"
        hint_text: "Nullam congue neque et tempor tincidunt. In ornare lacus ac arcu maximus ultricies. Quisque et ultrices nulla. Suspendisse potenti. Nunc imperdiet ornare leo ut ultrices. Praesent in quam in tellus dictum lacinia vitae vitae lacus. Nulla hendrerit feugiat urna eu gravida. Nam a molestie nisi, at semper neque. Quisque tincidunt venenatis bibendum. Morbi volutpat magna euismod ipsum consequat cursus. Etiam bibendum interdum ultricies."
        text: "Duis tempus est metus, in varius enim lobortis non. Nunc laoreet nisi vel lectus consequat, sed venenatis tellus dictum. Nunc ut nibh blandit ipsum bibendum dictum."
        bold: true
      - value: "extreme-value-4"
        hint_text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus sapien justo, lobortis elementum tortor in, luctus interdum turpis. Nam sit amet nulla nec arcu condimentum dapibus quis varius metus. Suspendisse cursus tristique diam et vestibulum. Proin nec lacinia tortor. Morbi at nisi id lorem aliquam ullamcorper. Pellentesque laoreet sit amet leo sodales ultricies. Suspendisse maximus efficitur odio in tristique."
        text: "Quisque tincidunt venenatis bibendum. Morbi volutpat magna euismod ipsum consequat cursus. Etiam bibendum interdum ultricies."
        bold: true
  with_error_on_form_group:
    data:
      name: "radio-group-error"
      id_prefix: "error"
      error_message: "Please select one option"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
  with_error_and_hint_on_form_group:
    description: ""
    data:
      name: "radio-group-error"
      id_prefix: "error"
      error_message: "Please select one option"
      hint: "Choose the option that suits"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
  with_error_items_on_form_group:
    data:
      name: "radio-group-error"
      id_prefix: "error"
      error_items:
      - text: Descriptive link to the question with an error 1
        href: '#example-error-1'
      - text: Descriptive link to the question with an error 2
        href: '#example-error-2'
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
  conditional:
    data:
      name: "radio-group-conditional"
      id_prefix: "conditional"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
        conditional: "You’ll need to prove your identity using Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
        conditional: "You’ll need to prove your identity using GOV.UK Verify"
  conditional_checked:
    data:
      name: "radio-group-conditional"
      id_prefix: "conditional-checked"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
        conditional: "You’ll need to prove your identity using Government Gateway"
        checked: true
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
        conditional: "You’ll need to prove your identity using GOV.UK Verify"
  tracking-url:
    data:
      name: "radio-group-tracking-url"
      id_prefix: "tracking-url"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
        url: "https://www.tax.service.gov.uk/gg/sign-in?continue=%2Fcheck-your-state-pension"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"
        url: "https://www.tax.service.gov.uk/check-your-state-pension/signin/verify?journey_hint=uk_idp_sign_in"
  inline:
    description: "When providing few options, radio buttons should be inline rather than stacked. We recommend this for two small options like yes and no, on and off"
    data:
      name: "inline-radios"
      inline: true
      items:
        - value: "on"
          text: "On"
        - value: "off"
          text: "Off"
  with_custom_id_attribute:
    data:
      name: "radio-group"
      id: "radio-group"
      items:
      - value: "government-gateway"
        text: "Use Government Gateway"
      - value: "govuk-verify"
        text: "Use GOV.UK Verify"