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) (preview all)

How do you want to sign in?

How to call this component

<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  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 active (in the active 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

Standard options

This component uses the component wrapper helper. It accepts the following options and applies them to the parent element of the component. See the component wrapper helper documentation for more detail.

  • id - accepts a string for the element ID attribute
  • data_attributes - accepts a hash of data attributes
  • aria - accepts a hash of aria attributes
  • classes - accepts a space separated string of classes, these should not be used for styling and must be prefixed with js-
  • margin_bottom - accepts a number from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale (defaults to no margin)
  • role - accepts a space separated string of roles
  • lang - accepts a language attribute value
  • open - accepts an open attribute value (true or false)
  • hidden - accepts an empty string, ‘hidden’, or ‘until-found’
  • tabindex - accepts an integer. The integer can also be passed as a string.
  • dir - accepts ‘rtl’, ‘ltr’, or ‘auto’.

With small radios (preview)

How do you want to sign in?

 
<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  name: "radio-group",
  small: true,
  items: [
    {
      value: "government-gateway",
      text: "Use Government Gateway"
    },
    {
      value: "govuk-verify",
      text: "Use GOV.UK Verify"
    }
  ]
} %>

With bold labels (preview)

Used to provide better contrast between long labels and hint text.

How do you want to sign in?
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", {
  heading: "How do you want to sign in?",
  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 custom bottom margin (preview)

The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale. It defaults to a margin bottom of 30px (6).

How do you want to sign in?

 
<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  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 (preview)

How do you want to sign in?
You’ll need to prove your identity using one of the following methods 
<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  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 legend (preview)

Legend text is automatically wrapped inside a h2. To render the text without it, heading_level must be set to 0.

What's it to do with? 
<%= render "govuk_publishing_components/components/radio", {
  name: "radio-group-legend",
  heading: "What's it to do with?",
  heading_level: 0,
  items: [
    {
      value: "yes",
      text: "Yes"
    },
    {
      value: "no",
      text: "No"
    }
  ]
} %>

With custom heading size (preview)

By default, text supplied for the legend is wrapped inside a h2.

The font size of this heading can be changed using the heading_size option. Valid options are s, m, l, xl, defaulting to m if no option is passed.

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 custom heading level (preview)

By default, text supplied for the legend is wrapped inside a h2. This can be changed using the heading_level option.

If heading_level is 1 and heading_size is not set, the text size will be xl.

What is your favourite colour?

 
<%= render "govuk_publishing_components/components/radio", {
  name: "radio-group-description",
  heading: "What is your favourite colour?",
  heading_level: 1,
  items: [
    {
      value: "red",
      text: "Red"
    },
    {
      value: "green",
      text: "Green"
    },
    {
      value: "blue",
      text: "Blue"
    }
  ]
} %>

With page heading and caption (preview)

A caption can be added using the heading_caption option. Captions will only be displayed if text for the heading option is present.

The pattern is used across GOV.UK to show a high-level section that this page belongs to.

Question 3 of 9

Is it snowing?

 
<%= render "govuk_publishing_components/components/radio", {
  name: "radio-group-heading",
  heading: "Is it snowing?",
  heading_caption: "Question 3 of 9",
  heading_level: 1,
  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?",
  heading_level: 1,
  hint: "Sleet or hail doesn’t count.",
  items: [
    {
      value: "yes",
      text: "Yes"
    },
    {
      value: "no",
      text: "No"
    }
  ]
} %>

With visually hidden heading (preview)

If the heading/legend on the radios is not required, it can be visually hidden using this option. It will still be visible to screen readers.

What is your favourite colour?

 
<%= render "govuk_publishing_components/components/radio", {
  name: "radio-group-visually-hidden-heading",
  heading: "What is your favourite colour?",
  visually_hidden_heading: true,
  items: [
    {
      value: "red",
      text: "Red"
    },
    {
      value: "green",
      text: "Green"
    },
    {
      value: "blue",
      text: "Blue"
    }
  ]
} %>

With description (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?",
  heading_level: 1,
  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 hint text on radios (preview)

How do you want to sign in?
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", {
  heading: "How do you want to sign in?",
  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)

How do you want to sign in?

 
<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  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)

How do you want to sign in?

 
<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  name: "radio-group-data-attributes",
  items: [
    {
      value: "government-gateway",
      text: "Use Government Gateway"
    },
    {
      value: "govuk-verify",
      text: "Use GOV.UK Verify",
      data_attributes: {
        "contextual-guidance": "government-gateway"
      }
    }
  ]
} %>

With custom id prefix (preview)

How do you want to sign in?

 
<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  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)

See related service manual guidance for this pattern

How do you want to sign in?
or
<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  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

How do you want to sign in?
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", {
  heading: "How do you want to sign in?",
  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)

How do you want to sign in?

Error: Please select one option 

<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  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)

How do you want to sign in?
Choose the option that suits

Error: Please select one option 

<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  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)

How do you want to sign in?

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", {
  heading: "How do you want to sign in?",
  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)

How do you want to sign in?
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", {
  heading: "How do you want to sign in?",
  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 (preview)

How do you want to sign in?
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", {
  heading: "How do you want to sign in?",
  name: "radio-group-conditional-checked",
  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 (preview)

How do you want to sign in?

 
<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  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

Have you changed your name?

 
<%= render "govuk_publishing_components/components/radio", {
  heading: "Have you changed your name?",
  name: "inline-radios",
  inline: true,
  items: [
    {
      value: "yes",
      text: "Yes"
    },
    {
      value: "no",
      text: "No"
    }
  ]
} %>

With custom id attribute (preview)

How do you want to sign in?

 
<%= render "govuk_publishing_components/components/radio", {
  heading: "How do you want to sign in?",
  name: "radio-group",
  id: "radio-group",
  items: [
    {
      value: "government-gateway",
      text: "Use Government Gateway"
    },
    {
      value: "govuk-verify",
      text: "Use GOV.UK Verify"
    }
  ]
} %>