Radios

Radios allow users to select a single option from a list.

Radios are grouped together in a fieldset with a legend that describes them, as shown in the examples on this page.

If you are asking just one question per page as recommended, you can set the contents of the legend as the page heading. This is good practice as it means that users of screen readers will only hear the contents once.

Important

Note that Rails now adds presence validation to associations automatically but usually we set relationships by assigning values to the foreign key column.

This results in errors being added to the object on attributes that don’t appear in the form, for example on department instead of department_id.

You can suppress this behaviour by adding optional: true to the relationship and manually adding the presence validation to the foreign key field yourself.

Radios collection with legend and hint text

Data

departments = [
  OpenStruct.new(id: 1, name: 'Sales'),
  OpenStruct.new(id: 2, name: 'Marketing'),
  OpenStruct.new(id: 3, name: 'Finance')
]

Input

= f.govuk_collection_radio_buttons :new_department_id,
  departments,
  :id,
  :name,
  legend: { text: 'Which department do you work for?' },
  hint: { text: 'There should be a sign near your desk' }

<%= f.govuk_collection_radio_buttons :new_department_id, departments, :id, :name, legend: { text: 'Which department do you work for?' }, hint: { text: 'There should be a sign near your desk' } %>

Output

Which department do you work for?

There should be a sign near your desk

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset" aria-describedby="person-new-department-id-hint">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      Which department do you work for?
    </legend>
    <input value="" autocomplete="off" type="hidden" name="person[new_department_id]" id="person_new_department_id" />
    <div class="govuk-hint" id="person-new-department-id-hint">
      There should be a sign near your desk
    </div>
    <div class="govuk-radios" data-module="govuk-radios">
      <div class="govuk-radios__item">
        <input id="person-new-department-id-1-field" class="govuk-radios__input" type="radio" value="1" name="person[new_department_id]" />
        <label for="person-new-department-id-1-field" class="govuk-label govuk-radios__label">
          Sales
        </label>
      </div>
      <div class="govuk-radios__item">
        <input id="person-new-department-id-2-field" class="govuk-radios__input" type="radio" value="2" name="person[new_department_id]" />
        <label for="person-new-department-id-2-field" class="govuk-label govuk-radios__label">
          Marketing
        </label>
      </div>
      <div class="govuk-radios__item">
        <input id="person-new-department-id-3-field" class="govuk-radios__input" type="radio" value="3" name="person[new_department_id]" />
        <label for="person-new-department-id-3-field" class="govuk-label govuk-radios__label">
          Finance
        </label>
      </div>
    </div>
  </fieldset>
</div>

Radios collection with descriptions

Often radios need a description to help the user pick the correct option. In addition to Rails’ collection form helper taking arguments for the identifier and label text for radio buttons, an extra argument can be passed for the description.

In this example, our source data has a description attribute which we want to form the hint text. The attribute name will be called on each option and if a description is present it will be displayed, if it is null or empty no hint will be rendered.

When descriptions are enabled in a radio button collection the labels are made bold by default. This makes the labels stand out from the hints. The auto bolding behaviour can be disabled by changing the default_collection_radio_buttons_auto_bold_labels configuration flag to false.

Data

lunch_options = [
  OpenStruct.new(
    id: 1,
    name: 'Salad',
    description: 'Lettuce, tomato and cucumber'
  ),
  OpenStruct.new(
    id: 2,
    name: 'Jacket potato',
    description: 'With cheese and baked beans'
  )
]

Input

= f.govuk_collection_radio_buttons :lunch_id,
  lunch_options,
  :id,
  :name,
  :description,
  legend: { text: 'What would you like for lunch?' }

<%= f.govuk_collection_radio_buttons :lunch_id, lunch_options, :id, :name, :description, legend: { text: 'What would you like for lunch?' } %>

Output

What would you like for lunch?

Lettuce, tomato and cucumber

With cheese and baked beans

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      What would you like for lunch?
    </legend>
    <input value="" autocomplete="off" type="hidden" name="person[lunch_id]" id="person_lunch_id" />
    <div class="govuk-radios" data-module="govuk-radios">
      <div class="govuk-radios__item">
        <input id="person-lunch-id-1-field" aria-describedby="person-lunch-id-1-hint" class="govuk-radios__input" type="radio" value="1" name="person[lunch_id]" />
        <label for="person-lunch-id-1-field" class="govuk-label govuk-label--s govuk-radios__label">
          Salad
        </label>
        <div class="govuk-hint govuk-radios__hint" id="person-lunch-id-1-hint">
          Lettuce, tomato and cucumber
        </div>
      </div>
      <div class="govuk-radios__item">
        <input id="person-lunch-id-2-field" aria-describedby="person-lunch-id-2-hint" class="govuk-radios__input" type="radio" value="2" name="person[lunch_id]" />
        <label for="person-lunch-id-2-field" class="govuk-label govuk-label--s govuk-radios__label">
          Jacket potato
        </label>
        <div class="govuk-hint govuk-radios__hint" id="person-lunch-id-2-hint">
          With cheese and baked beans
        </div>
      </div>
    </div>
  </fieldset>
</div>

Small radios

Use standard-sized radios in nearly all cases. However, smaller versions work well on pages where it’s helpful to make them less visually prominent.

For example, on a page of search results, the primary user need is to see the results. Using smaller radios lets users see and change search filters without distracting them from the main content.

Data

lunch_options = [
  OpenStruct.new(
    id: 1,
    name: 'Salad',
    description: 'Lettuce, tomato and cucumber'
  ),
  OpenStruct.new(
    id: 2,
    name: 'Jacket potato',
    description: 'With cheese and baked beans'
  )
]

Input

= f.govuk_collection_radio_buttons :wednesday_lunch_id,
  lunch_options,
  :id,
  :name,
  :description,
  small: true,
  legend: { text: 'What would you like for lunch on Wednesday?' }

<%= f.govuk_collection_radio_buttons :wednesday_lunch_id, lunch_options, :id, :name, :description, small: true, legend: { text: 'What would you like for lunch on Wednesday?' } %>

Output

What would you like for lunch on Wednesday?

Lettuce, tomato and cucumber

With cheese and baked beans

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      What would you like for lunch on Wednesday?
    </legend>
    <input value="" autocomplete="off" type="hidden" name="person[wednesday_lunch_id]" id="person_wednesday_lunch_id" />
    <div class="govuk-radios govuk-radios--small" data-module="govuk-radios">
      <div class="govuk-radios__item">
        <input id="person-wednesday-lunch-id-1-field" aria-describedby="person-wednesday-lunch-id-1-hint" class="govuk-radios__input" type="radio" value="1" name="person[wednesday_lunch_id]" />
        <label for="person-wednesday-lunch-id-1-field" class="govuk-label govuk-label--s govuk-radios__label">
          Salad
        </label>
        <div class="govuk-hint govuk-radios__hint" id="person-wednesday-lunch-id-1-hint">
          Lettuce, tomato and cucumber
        </div>
      </div>
      <div class="govuk-radios__item">
        <input id="person-wednesday-lunch-id-2-field" aria-describedby="person-wednesday-lunch-id-2-hint" class="govuk-radios__input" type="radio" value="2" name="person[wednesday_lunch_id]" />
        <label for="person-wednesday-lunch-id-2-field" class="govuk-label govuk-label--s govuk-radios__label">
          Jacket potato
        </label>
        <div class="govuk-hint govuk-radios__hint" id="person-wednesday-lunch-id-2-hint">
          With cheese and baked beans
        </div>
      </div>
    </div>
  </fieldset>
</div>

Inline radios

When there are only two options, you can either stack the radios or display them inline.

Input

= f.govuk_collection_radio_buttons :thursday_lunch_id,
  lunch_options,
  :id,
  :name,
  inline: true,
  legend: { text: 'What would you like for lunch on Thursday?' }

<%= f.govuk_collection_radio_buttons :thursday_lunch_id, lunch_options, :id, :name, inline: true, legend: { text: 'What would you like for lunch on Thursday?' } %>

Output

What would you like for lunch on Thursday?

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      What would you like for lunch on Thursday?
    </legend>
    <input value="" autocomplete="off" type="hidden" name="person[thursday_lunch_id]" id="person_thursday_lunch_id" />
    <div class="govuk-radios govuk-radios--inline" data-module="govuk-radios">
      <div class="govuk-radios__item">
        <input id="person-thursday-lunch-id-1-field" class="govuk-radios__input" type="radio" value="1" name="person[thursday_lunch_id]" />
        <label for="person-thursday-lunch-id-1-field" class="govuk-label govuk-radios__label">
          Salad
        </label>
      </div>
      <div class="govuk-radios__item">
        <input id="person-thursday-lunch-id-2-field" class="govuk-radios__input" type="radio" value="2" name="person[thursday_lunch_id]" />
        <label for="person-thursday-lunch-id-2-field" class="govuk-label govuk-radios__label">
          Jacket potato
        </label>
      </div>
    </div>
  </fieldset>
</div>

Radios fieldset with conditional content and a divider

The form builder does not keep track of its contents so to ensure the error summary correctly links to the first radio button link_errors must be set to true

If your list of options is hard-coded or you want to add extra customisation, like inserting a text divider, the #govuk_radio_buttons_fieldset helper offers additional flexibility.

Any content passed into #govuk_radio_button as a block will be revealed when the radio button is selected.

Input

= f.govuk_radio_buttons_fieldset(:old_department_id, legend: { size: 'm', text: 'Which department do you work in?' }) do
  = f.govuk_radio_button :old_department_id, 'it', label: { text: 'Information Technology' }, link_errors: true
  = f.govuk_radio_button :old_department_id, 'marketing', label: { text: 'Marketing' }, hint: { text: 'Includes Sales and Digital Marketing' }
  = f.govuk_radio_divider
  = f.govuk_radio_button :old_department_id, 'other', label: { text: 'Other' } do
    = f.govuk_text_field :old_department_description,
      label: { text: 'Which department did you work in most recently?' }

<%= f.govuk_radio_buttons_fieldset(:old_department_id, legend: { size: 'm', text: 'Which department do you work in?' }) do %>
  <%= f.govuk_radio_button :old_department_id, 'it', label: { text: 'Information Technology' }, link_errors: true %>
  <%= f.govuk_radio_button :old_department_id, 'marketing', label: { text: 'Marketing' }, hint: { text: 'Includes Sales and Digital Marketing' } %>
  <%= f.govuk_radio_divider %>
  <%= f.govuk_radio_button :old_department_id, 'other', label: { text: 'Other' } do %>
    <%= f.govuk_text_field :old_department_description, label: { text: 'Which department did you work in most recently?' } %>
  <% end %>
<% end %>

Output

Which department do you work in?

Includes Sales and Digital Marketing

or

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      Which department do you work in?
    </legend>
    <div class="govuk-radios" data-module="govuk-radios">
      <div class="govuk-radios__item">
        <input id="person-old-department-id-it-field" class="govuk-radios__input" type="radio" value="it" name="person[old_department_id]" />
        <label for="person-old-department-id-it-field" class="govuk-label govuk-radios__label">
          Information Technology
        </label>
      </div>
      <div class="govuk-radios__item">
        <input id="person-old-department-id-marketing-field" class="govuk-radios__input" aria-describedby="person-old-department-id-marketing-hint" type="radio" value="marketing" name="person[old_department_id]" />
        <label for="person-old-department-id-marketing-field" class="govuk-label govuk-radios__label">
          Marketing
        </label>
        <div class="govuk-hint govuk-radios__hint" id="person-old-department-id-marketing-hint">
          Includes Sales and Digital Marketing
        </div>
      </div>
      <div class="govuk-radios__divider">
        or
      </div>
      <div class="govuk-radios__item">
        <input id="person-old-department-id-other-field" class="govuk-radios__input" data-aria-controls="person-old-department-id-other-conditional" type="radio" value="other" name="person[old_department_id]" />
        <label for="person-old-department-id-other-field" class="govuk-label govuk-radios__label">
          Other
        </label>
      </div>
      <div class="govuk-radios__conditional govuk-radios__conditional--hidden" id="person-old-department-id-other-conditional">
        <div class="govuk-form-group">
          <label for="person-old-department-description-field" class="govuk-label">
            Which department did you work in most recently?
          </label>
          <input id="person-old-department-description-field" class="govuk-input" type="text" name="person[old_department_description]" />
        </div>
      </div>
    </div>
  </fieldset>
</div>

Populating values, labels and hints with procs

It’s often convenient to hold label and hint text in locale or configuration files. This approach allows content changes to be made in the repository rather than modifying via data migrations.

To support this behaviour the form builder allows Ruby Procs to be supplied for the :value_method, :text_method and :hint_method parameters. They each take a single argument, item, which is object representing the radio button.

Data

laptops = %w(thinkpad xps macbook_pro zenbook)

Localisation data

laptops:
  names:
    thinkpad: Lenovo ThinkPad X1 Carbon
    macbook_pro: MacBook Pro
    xps: Dell XPS
    zenbook: Asus ZenBook
  descriptions:
    macbook_pro: |-
      The MacBook Pro is a line of Macintosh portable computers
      introduced in January 2006, by Apple Inc.
    thinkpad: |-
      ThinkPad, known for their minimalist, black and boxy design, is a
      line of business-oriented laptops designed, developed, marketed,
      and sold by Lenovo (formerly IBM)
    zenbook: |-
      Zenbook are a family of ultrabooks – low-bulk laptop computers –
      produced by Asus.
    xps: |-
      Dell XPS 'Xtreme Performance System' is a line of high
      performance computers manufactured by Dell.

Input

= f.govuk_collection_radio_buttons :laptop,
  laptops,
  ->(option) { option },
  ->(option) { I18n.t('laptops.names.' + option) },
  ->(option) { I18n.t('laptops.descriptions.' + option) },
  legend: { text: "Which laptop would you like to use?" }

<%= f.govuk_collection_radio_buttons :laptop, laptops, ->(option) { option }, ->(option) { I18n.t('laptops.names.' + option) }, ->(option) { I18n.t('laptops.descriptions.' + option) }, legend: { text: "Which laptop would you like to use?" } %>

Output

Which laptop would you like to use?

ThinkPad, known for their minimalist, black and boxy design, is a line of business-oriented laptops designed, developed, marketed, and sold by Lenovo (formerly IBM)

Dell XPS ‘Xtreme Performance System’ is a line of high performance computers manufactured by Dell.

The MacBook Pro is a line of Macintosh portable computers introduced in January 2006, by Apple Inc.

Zenbook are a family of ultrabooks – low-bulk laptop computers – produced by Asus.

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      Which laptop would you like to use?
    </legend>
    <input value="" autocomplete="off" type="hidden" name="person[laptop]" id="person_laptop" />
    <div class="govuk-radios" data-module="govuk-radios">
      <div class="govuk-radios__item">
        <input id="person-laptop-thinkpad-field" aria-describedby="person-laptop-thinkpad-hint" class="govuk-radios__input" type="radio" value="thinkpad" name="person[laptop]" />
        <label for="person-laptop-thinkpad-field" class="govuk-label govuk-label--s govuk-radios__label">
          Lenovo ThinkPad X1 Carbon
        </label>
        <div class="govuk-hint govuk-radios__hint" id="person-laptop-thinkpad-hint">
          ThinkPad, known for their minimalist, black and boxy design, is a
          line of business-oriented laptops designed, developed, marketed,
          and sold by Lenovo (formerly IBM)
        </div>
      </div>
      <div class="govuk-radios__item">
        <input id="person-laptop-xps-field" aria-describedby="person-laptop-xps-hint" class="govuk-radios__input" type="radio" value="xps" name="person[laptop]" />
        <label for="person-laptop-xps-field" class="govuk-label govuk-label--s govuk-radios__label">
          Dell XPS
        </label>
        <div class="govuk-hint govuk-radios__hint" id="person-laptop-xps-hint">
          Dell XPS 'Xtreme Performance System' is a line of high
          performance computers manufactured by Dell.
        </div>
      </div>
      <div class="govuk-radios__item">
        <input id="person-laptop-macbook-pro-field" aria-describedby="person-laptop-macbook-pro-hint" class="govuk-radios__input" type="radio" value="macbook_pro" name="person[laptop]" />
        <label for="person-laptop-macbook-pro-field" class="govuk-label govuk-label--s govuk-radios__label">
          MacBook Pro
        </label>
        <div class="govuk-hint govuk-radios__hint" id="person-laptop-macbook-pro-hint">
          The MacBook Pro is a line of Macintosh portable computers
          introduced in January 2006, by Apple Inc.
        </div>
      </div>
      <div class="govuk-radios__item">
        <input id="person-laptop-zenbook-field" aria-describedby="person-laptop-zenbook-hint" class="govuk-radios__input" type="radio" value="zenbook" name="person[laptop]" />
        <label for="person-laptop-zenbook-field" class="govuk-label govuk-label--s govuk-radios__label">
          Asus ZenBook
        </label>
        <div class="govuk-hint govuk-radios__hint" id="person-laptop-zenbook-hint">
          Zenbook are a family of ultrabooks – low-bulk laptop computers –
          produced by Asus.
        </div>
      </div>
    </div>
  </fieldset>
</div>