Alpha

This is an alpha release of our documentation site. View the roadmap.

Radio group

On this page

A radio allows a user to select only one option from a group of exclusive choices and it is usually displayed in a radio group.

Open example in a new tab
Example radio group 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--radio">
    <legend class="cads-form-field__label">
      Example radio group
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-0" name="radio-buttons" value="1">
      <label class="cads-form-group__label" for="radio-buttons-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-1" name="radio-buttons" value="2">
      <label class="cads-form-group__label" for="radio-buttons-1">
        Option 2
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::RadioGroup.new(
  legend: "Example radio group",
  name: "radio-buttons"
) do |c|
  c.with_inputs([
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" }
  ])
end %>

When not to use

Do not use a radio group if the user:

  • should be able to select one or more choices from a list of options (use a checkbox group for this)
  • there is only one checkbox in the list of options, for example agreeing to terms and conditions (use checkbox for this)

How it works

Inline

Open example in a new tab
Example radio group 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--radio cads-radio-group--inline">
    <legend class="cads-form-field__label">
      Example radio group
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-inline-0" name="radio-buttons-inline" value="1">
      <label class="cads-form-group__label" for="radio-buttons-inline-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-inline-1" name="radio-buttons-inline" value="2">
      <label class="cads-form-group__label" for="radio-buttons-inline-1">
        Option 2
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::RadioGroup.new(
  legend: "Example radio group",
  name: "radio-buttons-inline",
  options: {
    layout: :inline
  }
) do |c|
  c.with_inputs([
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" }
  ])
end %>

Use inline radios if there are only 2 options and the text is short.

Stacked

Open example in a new tab
Example radio group 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--radio">
    <legend class="cads-form-field__label">
      Example radio group
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-long-0" name="radio-buttons-long" value="1">
      <label class="cads-form-group__label" for="radio-buttons-long-0">
        This option is pretty long and will probably wrap over multiple lines
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-long-1" name="radio-buttons-long" value="2">
      <label class="cads-form-group__label" for="radio-buttons-long-1">
        This option is also pretty long, too long even, and will almost definitely wrap over multiple lines
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::RadioGroup.new(
  legend: "Example radio group",
  name: "radio-buttons-long"
) do |c|
  c.with_inputs([
    { label: "This option is pretty long and will probably wrap over multiple lines", value: "1" },
    { label: "This option is also pretty long, too long even, and will almost definitely wrap over multiple lines", value: "2" }
  ])
end %>

Use stacked radios if there are more than 2 options or the text is very long.

With hint

Use hint text for help that’s relevant to the majority of users, based on the needs of your service.

Open example in a new tab
Example radio group

This is the hint text

<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--radio">
    <legend class="cads-form-field__label">
      Example radio group
    </legend>
    <p class="cads-form-field__hint">This is the hint text</p>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-hint-0" name="radio-buttons-hint" value="1">
      <label class="cads-form-group__label" for="radio-buttons-hint-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-hint-1" name="radio-buttons-hint" value="2">
      <label class="cads-form-group__label" for="radio-buttons-hint-1">
        Option 2
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::RadioGroup.new(
  legend: "Example radio group",
  name: "radio-buttons-hint",
  options: {
    hint: "This is the hint text"
  }
) do |c|
  c.with_inputs([
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" }
  ])
end %>

With optional field marker

Open example in a new tab
Example radio group (optional) 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--radio">
    <legend class="cads-form-field__label">
      Example radio group
      <span class="cads-form-field__optional">(optional)</span>
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-optional-0" name="radio-buttons-optional" value="1">
      <label class="cads-form-group__label" for="radio-buttons-optional-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-optional-1" name="radio-buttons-optional" value="2">
      <label class="cads-form-group__label" for="radio-buttons-optional-1">
        Option 2
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::RadioGroup.new(
  legend: "Example radio group",
  name: "radio-buttons-optional",
  options: {
    optional: true
  }
) do |c|
  c.with_inputs([
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" }
  ])
end %>

With error message

Error messages are used to highlight where users need to change information. They’re used together with an error summary.

Open example in a new tab
Example radio group

Select an option

<div class="cads-form-field cads-form-field--has-error">
  <div class="cads-form-field__error-marker"></div>
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--radio">
    <legend class="cads-form-field__label">
      Example radio group
    </legend>
    <p class="cads-form-field__error-message"  id="radio-buttons-error-error">Select an option</p>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-error-0" name="radio-buttons-error" value="1" aria-describedby="radio-buttons-error-error" aria-invalid="true">
      <label class="cads-form-group__label" for="radio-buttons-error-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-error-1" name="radio-buttons-error" value="2" aria-describedby="radio-buttons-error-error" aria-invalid="true">
      <label class="cads-form-group__label" for="radio-buttons-error-1">
        Option 2
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::RadioGroup.new(
  legend: "Example radio group",
  name: "radio-buttons-error",
  options: {
    error_message: "Select an option"
  }
) do |c|
  c.with_inputs([
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" }
  ])
end %>

Small radios

Open example in a new tab
Example radio group 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--radio cads-radio-group--small">
    <legend class="cads-form-field__label">
      Example radio group
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-small-0" name="radio-buttons-small" value="1">
      <label class="cads-form-group__label" for="radio-buttons-small-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-small-1" name="radio-buttons-small" value="2">
      <label class="cads-form-group__label" for="radio-buttons-small-1">
        Option 2
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::RadioGroup.new(
  legend: "Example radio group",
  name: "radio-buttons-small",
  options: {
    size: :small
  }
) do |c|
  c.with_inputs([
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" }
  ])
end %>

Use standard radios in almost all cases. Use small radios to make them less visually prominent or on pages with lots of dense information, such as caseworking software. Small radios can be stacked or inline.

Implementation

You must always have a label associated with the input element.

The components we provide use wrap radio groups in a fieldset. In this context the ‘label’ is typically the fieldset legend, as every radio option is a label + input in its own right.

Using with Rails

If you are using the citizens_advice_components gem, you can call the component from within a following the example below.

The radio buttons themselves can be defined using a simple hash, and passed into the RadioGroup component like this:

<%= render CitizensAdviceComponents::RadioGroup.new(
  legend: "Example radio group",
  name: "radio-buttons"
) do |c|
  c.with_inputs([
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" }
  ])
end %>

Additional attributes (View component only)

Any additional key/value pairs (beyond label and value) in your radio button definition will be added to the input.

Open example in a new tab
Example radio group 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--radio">
    <legend class="cads-form-field__label">
      Example radio group
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-attrs-0" name="radio-buttons-attrs" value="1" data-testid="first-input">
      <label class="cads-form-group__label" for="radio-buttons-attrs-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-attrs-1" name="radio-buttons-attrs" value="2" data-testid="second-input">
      <label class="cads-form-group__label" for="radio-buttons-attrs-1">
        Option 2
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::RadioGroup.new(
  legend: "Example radio group",
  name: "radio-buttons-attrs"
) do |c|
  c.with_inputs([
    { label: "Option 1", value: "1", "data-testid": "first-input" },
    { label: "Option 2", value: "2", "data-testid": "second-input" }
  ])
end %>

With heading in the legend

Used for one question per page forms. Using similar approach to the one described in gov.uk - Making labels and legends headings.

Open example in a new tab

Example radio group

 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--radio">
    <legend class="cads-form-field__label cads-form-field__label--with-heading">
      <h1 class="cads-form-field__heading">Example radio group</h1>
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-attrs-0" name="radio-buttons-attrs" value="1">
      <label class="cads-form-group__label" for="radio-buttons-attrs-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-attrs-1" name="radio-buttons-attrs" value="2">
      <label class="cads-form-group__label" for="radio-buttons-attrs-1">
        Option 2
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::RadioGroup.new(
  legend: "Example radio group",
  name: "radio-buttons-attrs",
  options: {
    legend_heading: true
  }
) do |c|
  c.with_inputs([
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" }
  ])
end %>

Checkbox ids (View component only)

The id attribute for each input will be automatically generated for you by the view component. They will take the form of: [name]-[index], where [index] is the position of the checkbox in the array passed into c.with_inputs above. eg my-checkbox-0, my-checkbox-1, etc. It is also possible to have an id which is not generated by the name by passing an id attribute. In this case, the format will be [id]-[index].

Open example in a new tab
Example radio group 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--radio">
    <legend class="cads-form-field__label">
      Example radio group
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-test-0" name="radio-buttons[test]" value="1">
      <label class="cads-form-group__label" for="radio-buttons-test-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="radio" id="radio-buttons-test-1" name="radio-buttons[test]" value="2">
      <label class="cads-form-group__label" for="radio-buttons-test-1">
        Option 2
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::RadioGroup.new(
  legend: "Example radio group",
  name: "radio-buttons[test]",
  id: "radio-buttons-test"
) do |c|
  c.with_inputs([
    { label: "Option 1", value: 1 },
    { label: "Option 2", value: 2 },
  ])
end %>

Component arguments

Argument Description
Argument name Description Required, field name
Argument id Description Optional, allows customising the id. By default the id is autogenerated based on the name
Argument label Description Required, the text for the label associated with the input
Argument options Description Optional, a hash with one or more of the following values
Argument hint Description → Optional, hint text for the input
Argument error_message Description → Optional, an error message for the input
Argument optional Description → Optional, boolean indicating the field is optional (ie not required)
Argument size Description → Optional, the size of the radio buttons. One of nil, :small, :regular
Argument layout Description → Optional, the layout of the radio buttons. One of nil, :inline, :list
Argument legend_heading Description → Optional, wraps the text inside the legend in h1