Radio buttons

May also be known as:

radio options, option buttons, or simply options.

Overview

Radio buttons are a type of control input that allow users to select one item from a predefined set of mutually exclusive options.

Default example

Vertically stacked radio buttons.

Example

Theme

White
Light
Alt
Dark
Dark-alt

*Label Select an option

Laptop

Phone

Tablet

<!-- This code displays a fieldset containing a list of radio buttons -->

<!-- The fieldset contains a legend element to provide a description of the radio buttons -->
<fieldset class="qld__fieldset" aria-describedby="radio-example-hint">

    <legend class="qld__fieldset__legend">
    <abbr title="required">*</abbr>Label
    </legend>

    <!-- The hint text provides instructions for the user -->
    <span class="qld__hint-text" id="radio-example-hint">Select an option</span>

    <!-- The radio buttons are contained in a group with a qld custom class 'qld_form-field' -->
    <div class="qld_form-field qld__control-group">

        <!-- Radio option 1 -->
        <div class="qld__control-input qld__control-input--block">
            <input class="qld__control-input__input" type="radio" name="1-radio-ex" id="1-rb-laptop" role="radio"
                aria-checked="false">
            <label class="qld__control-input__text" for="1-rb-laptop">Laptop</label>
        </div>

        <!-- Radio option 2 -->
        <div class="qld__control-input qld__control-input--block">
            <input class="qld__control-input__input" type="radio" name="1-radio-ex" id="1-rb-phone" role="radio"
                aria-checked="false">
            <label class="qld__control-input__text" for="1-rb-phone">Phone</label>
        </div>

        <!-- Radio option 3 -->
        <div class="qld__control-input qld__control-input--block">
            <input class="qld__control-input__input" type="radio" name="1-radio-ex" id="1-rb-tablet" role="radio"
                aria-checked="false">
            <label class="qld__control-input__text" for="1-rb-tablet">Tablet</label>
        </div>

    </div>
</fieldset>

Valid and invalid states

Adds a border around the control inputs to indicate valid or invalid selections.

Disabled control inputs

Disabled control inputs can be used to indicate inputs that are no longer valid or expired.

Example

Theme

White
Light
Alt
Dark
Dark-alt

Label

Select an option

Laptop

Phone

Tablet

<!-- Start of the fieldset element-->
<fieldset class="qld__fieldset" aria-describedby="radio-disabled-example-hint">

<!-- Fieldset legend describing the purpose of the radio buttons -->
<legend class="qld__fieldset__legend" id="legend-disabled">Label</legend>

<!-- Hint text providing instructions for the user -->
<div class="qld__hint-text" id="radio-disabled-example-hint">Select an option</div>

<!-- Start of the form field container with a qld custom class 'qld_form-field' -->
<div class="qld_form-field qld__control-group">

    <!-- Radio option 1-->
    <div class="qld__control-input qld__control-input--block">
        <input class="qld__control-input__input" disabled type="radio" name="4-radio-ex" id="4-rb-laptop" role="radio" aria-disabled="true">
        <label class="qld__control-input__text" for="4-rb-laptop">Laptop</label>
    </div>

    <!-- Radio option 2-->
    <div class="qld__control-input qld__control-input--block">
        <input class="qld__control-input__input" disabled type="radio" name="4-radio-ex" id="4-rb-phone" role="radio" aria-disabled="true">
        <label class="qld__control-input__text" for="4-rb-phone">Phone</label>
    </div>

    <!-- Radio option 3-->
    <div class="qld__control-input qld__control-input--block">
        <input class="qld__control-input__input" disabled type="radio" name="4-radio-ex" id="4-rb-tablet" role="radio" aria-disabled="true">
        <label class="qld__control-input__text" for="4-rb-tablet">Tablet</label>
    </div>

</div>

</fieldset>

Usage guidelines

When to use

Use radio buttons when you want users to choose only one option from a set of 2 to 7 related, mutually exclusive options.
Use radio buttons when the available options are static and don't change dynamically.
Use radio buttons when you want to display all available options at once, making it easy for users to compare and choose.

When not to use

Don't use radio buttons if users might need to select more than one option. In this case, you should use the checkboxes component instead.
Don't use radio buttons if there's only one option, as it doesn't make sense for the user to choose between one option.
Don't use radio buttons when the list of options is too long (more than 7). Use a dropdown menu or another selection method instead.

How to use

Size

Use the default-sized radios in most cases. However, smaller versions can be useful when you want to make them less visually prominent. For instance, on a search results page, using smaller radios can let users change search filters without distracting them from the main content.

Include "None of the above"

Users should be able to deselect an option if they change their mind. Therefore, it's essential to include a "None of the above" or "I do not know" option if they're valid choices.

Don't preselect

Don't pre-select an option for users, as it can confuse them and lead to incorrect answers. Let users choose for themselves.Setting a default value can influence user decisions or come across as pushy. Only use default selection if you have data to back it up.

Group radio buttons

Group radio buttons together using a <fieldset> with a <legend> that describes them. Make sure the grouping is meaningful and logical.

Use label as target

Make sure users can select either the text label or the radio button to choose an option.

List items vertically

Listing options vertically makes them easier to read than when they're listed horizontally, which can cause confusion.

Use a logical order

Organise the selection options in a meaningful way, such as alphabetical or most-frequent to least-frequent, to help users find what they're looking for quickly.

Headings

If you're asking one question per page, use the contents of the <legend> as the page heading. This is good practice, especially for screen readers, as it means users will only hear the contents once.

For more guidelines on how to structure and lay out radio buttons see Australian Government Style Manual.

Research and rationale

Our design for radio buttons is based on the GOV.UK (UK Government, 2023, Radio section) and DTA (Digital Transformation Agency, 2018, Control input section).

Our radio buttons are much larger than default browser inputs to provide larger hit/target areas for touchscreen devices or mobility impaired users. There's a smaller version available where this is not practical.

Like all our form elements, our radio buttons used the border-alt colour to determine their border colours as this is designed for maximum contrast.

For more information and our form designs and rationale see the forms component.

Classes and utilities

Name	Description
`qld__fieldset`	Applies to fieldset element when radio are grouped.
`qld__fieldset__legend`	Defines the overarching description of the form group.
`qld__hint-text`	Consistent style for all hint text on form fields.
`qld__control-group`	Use to apply styles to a group radio buttons.
`qld__control-input`	Default class for all input controls fields.
`qld__control-input--block`	Class fro when input fields are listed vertically.
`qld__control-input__text`	Class that defines input field labels.
`qld__input--valid`	Applied to input element to style valid fields.
`qld__input--error`	Applied to input element to style invalid fields.
`disabled`	Added to input field to set disabled state.

Accessible radio button requirements

Keep these considerations in mind if you're modifying the Design System or creating a custom component.

WCAG guidelines

1.3.1 Info and Relationships

Organise and structure the form in a logical and predictable manner. Use proper markup to convey the hierarchy and relationships between form elements, such as fieldsets and legends for grouping related fields.

2.4.6 Headings and Labels

Provide clear and descriptive labels for form fields and headings for sections. This helps users understand the purpose of each field and the structure of the form.

2.1 Keyboard accessible

Ensure that radio buttons are navigable and selectable using the keyboard (tab and spacebar).

2.4.7 Focus Visible

Provide a visible focus indicator for radio buttons to help users with different input methods.

1.4.3 Contrast (Minimum)

Ensure that the colour contrast between the text labels and background meets WCAG 2.1 Level AA requirements.

3.3.1 Error Identification

Clearly identify and describe any errors that occur during form submission or input validation. Provide guidance on how to fix the errors.

3.3.2 Labels or Instructions

Clear and descriptive labels

Ensure that radio button labels are clear, concise, and provide enough context for screen reader users.

3.3.3 Error Suggestion

If an input error is automatically detected, provide suggestions for correcting the error, where possible.

3.3.4 Error Prevention (Legal, Financial, Data)

For forms that involve legal, financial, or sensitive data transactions, provide mechanisms to review and correct information before submission or allow users to confirm or reverse their actions.

4.1.2 Name, Role, Value

Use the relevant HTML to ensure the radios and group of radios have the correct Names, Roles, and Values.

In our examples we use the <fieldset> and <legend> elements to group our controls. The <fieldset> element provides a container for related form controls, and the <legend> element acts as a heading to identify the group.

When using this method it is not necessary to include aria roles and attributes.

ARIA roles and attributes

When it is not possible to use the HTML elements, ensure the correct ARIA Roles, States, and Properties are present.

If you are not using <fieldset> and <legend> use role="radiogroup" for the container and role="radio" for each radio button.

Use aria-labelledby to associate a visible label with the radio group and aria-describedby to provide additional information or instructions if needed.

Consult the Radio Pattern of ARIA Authoring Practices Guide for the full list of WAI-ARIA Roles, States, and Properties.

References

Digital Transformation Agency (2018) Control input, Gold Design System (Formerly DTA), accessed 10 April 2023.

W3C (2018) Web Content Accessibility Guidelines (WCAG) 2.1, World Wide Web Consortium, accessed 10 April 2023.

GOV.UK (n.d.) Radios, GOV.UK Design System, accessed 27 April 2023.

W3C Web Accessibility Initiative (2021) ARIA Authoring Practices Guide (APG) Radio Pattern, ARIA Authoring Practices Guide, W3C, accessed 27 April 2023.

United States Web Design System (n.d.) Radio buttons, United States Web Design System, accessed 27 April 2023.

Last updated: May 2024