1. Government Frontend Component Guide
  2. Form radio button

Component

Form radio button

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.

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.

Search for usage of this component on GitHub

How it looks (preview all)

How to call this component

<%= render "govuk_publishing_components/components/radio", {
  name: "radio-group",
  items: [
    {
      value: "government-gateway",
      text: "Use Government Gateway"
    },
    {
      value: "govuk-verify",
      text: "Use GOV.UK Verify"
    }
  ]
} %>

GOV.UK Design System

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

Accessibility acceptance 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
  • 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

  • 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.

Other examples

With small radios (preview)

<%= render "govuk_publishing_components/components/radio", {
  name: "radio-group",
  small: true,
  items: [
    {
      value: "government-gateway",
      text: "Use Government Gateway"
    },
    {
      value: "govuk-verify",
      text: "Use GOV.UK Verify"
    }
  ]
} %>

With bold (preview)

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

You'll have a user ID if you've signed up to do things like sign up Self Assessment tax return online.
You'll have an account if you've already proved your identity with a certified company, such as the Post Office.
<%= render "govuk_publishing_components/components/radio", {
  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 hint on form group (preview)

You’ll need to prove your identity using one of the following methods
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

This adds a legend element containing the text supplied.

Are you hungry?
<%= render "govuk_publishing_components/components/radio", {
  name: "radio-group-heading",
  heading: "Are you hungry?",
  items: [
    {
      value: "yes",
      text: "Yes"
    },
    {
      value: "no",
      text: "No"
    }
  ]
} %>

With heading and hint (preview)

What is your favourite colour?
If your favourite is not below, pick the colour closest to it.
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

This adds a H1 element containing the text supplied.

Is it raining?

<%= render "govuk_publishing_components/components/radio", {
  name: "radio-group-heading",
  heading: "Is it raining?",
  is_page_heading: true,
  items: [
    {
      value: "yes",
      text: "Yes"
    },
    {
      value: "no",
      text: "No"
    }
  ]
} %>

With page heading and hint (preview)

Is it snowing?

Sleet or hail doesn’t count.
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

What is your favourite colour?
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.
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

What is your favourite colour?
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.
Choose the colour
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

What is your favourite colour?

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.
Choose the colour
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

What is your favourite colour?
<%= render "govuk_publishing_components/components/radio", {
  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 hint text on radios (preview)

You'll have a user ID if you've signed up to do things like sign up Self Assessment tax return online.
You'll have an account if you've already proved your identity with a certified company, such as the Post Office.
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

or
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

Note that the :or option is documented as a string due to a bug

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.
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.
or
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.
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.
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

Error: Please select one option
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

Choose the option that suits
Error: Please select one option
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

Error: Descriptive link to the question with an error 1
Descriptive link to the question with an error 2
<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

You’ll need to prove your identity using Government Gateway
You’ll need to prove your identity using GOV.UK Verify
<%= render "govuk_publishing_components/components/radio", {
  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"
    }
  ]
} %>

Tracking-url (preview)

<%= render "govuk_publishing_components/components/radio", {
  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 (preview)

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

<%= render "govuk_publishing_components/components/radio", {
  name: "inline-radios",
  inline: true,
  items: [
    {
      value: "on",
      text: "On"
    },
    {
      value: "off",
      text: "Off"
    }
  ]
} %>