Components

Radio buttons

Radio buttons allow users to select exactly one choice from a group.

Passed WCAG 2.1 AA

About the radio buttons component

Radio buttons are a common way to allow users to make a single selection from a list of options. Since only one radio button can be selected at a time (within the same group), each available choice must be its own item and label. In contrast, checkboxes may show a single label, with the checked/unchecked status of the item meaning opposite things. For example, a checkbox could have a single input/label and legend that says “I have read the terms and conditions.” Radio buttons would need two inputs/labels for the same legend, “No” and “Yes”.

Once a user selects one of the radio buttons in a group, the group can’t be easily reset to displaying no radio buttons selected. One possible solution would be to add a “none of the above” option to a radio button group, which would allow users to effectively unselect the other radio buttons in that group.

Default

Select one historical figure

Tile

Select one historical figure 

<h3 class="site-preview-heading">Default</h3>
<fieldset class="usa-fieldset">
  <legend class="usa-legend usa-legend">Select one historical figure</legend>
  <div class="usa-radio">
    <input
      class="usa-radio__input"
      id="historical-truth"
      type="radio"
      name="historical-figures"
      value="sojourner-truth"
      checked="checked"
    />
    <label class="usa-radio__label" for="historical-truth"
      >Sojourner Truth</label
    >
  </div>
  <div class="usa-radio">
    <input
      class="usa-radio__input"
      id="historical-douglass"
      type="radio"
      name="historical-figures"
      value="frederick-douglass"
    />
    <label class="usa-radio__label" for="historical-douglass"
      >Frederick Douglass</label
    >
  </div>
  <div class="usa-radio">
    <input
      class="usa-radio__input"
      id="historical-washington"
      type="radio"
      name="historical-figures"
      value="booker-t-washington"
    />
    <label class="usa-radio__label" for="historical-washington"
      >Booker T. Washington</label
    >
  </div>
  <div class="usa-radio">
    <input
      class="usa-radio__input"
      id="historical-carver"
      type="radio"
      name="historical-figures"
      value="george-washington-carver"
      disabled="disabled"
    />
    <label class="usa-radio__label" for="historical-carver"
      >George Washington Carver</label
    >
  </div>
</fieldset>

<h3 class="site-preview-heading">Tile</h3>
<form class="usa-form">
  <fieldset class="usa-fieldset">
    <legend class="usa-legend">Select one historical figure</legend>
    <div class="usa-radio">
      <input
        class="usa-radio__input usa-radio__input--tile"
        id="historical-truth-2"
        type="radio"
        name="historical-figures-2"
        value="sojourner-truth"
        checked="checked"
      />
      <label class="usa-radio__label" for="historical-truth-2"
        >Sojourner Truth</label
      >
    </div>
    <div class="usa-radio">
      <input
        class="usa-radio__input usa-radio__input--tile"
        id="historical-douglass-2"
        type="radio"
        name="historical-figures-2"
        value="frederick-douglass"
      />
      <label class="usa-radio__label" for="historical-douglass-2"
        >Frederick Douglass
        <span class="usa-checkbox__label-description"
          >This is optional text that can be used to describe the label in more
          detail.</span
        ></label
      >
    </div>
    <div class="usa-radio">
      <input
        class="usa-radio__input usa-radio__input--tile"
        id="historical-washington-2"
        type="radio"
        name="historical-figures-2"
        value="booker-t-washington"
      />
      <label class="usa-radio__label" for="historical-washington-2"
        >Booker T. Washington</label
      >
    </div>
    <div class="usa-radio">
      <input
        class="usa-radio__input usa-radio__input--tile"
        id="historical-carver-2"
        type="radio"
        name="historical-figures-2"
        value="george-washington-carver"
        disabled="disabled"
      />
      <label class="usa-radio__label" for="historical-carver-2"
        >George Washington Carver</label
      >
    </div>
  </fieldset>
</form>

Guidance

When to use the radio buttons component

  • To display a single selection. When users need to select only one option from a set of mutually exclusive choices.

When to consider something else

  • Multiple selections. If users need to select more than one option or if there’s only one item to select, use checkboxes instead.
  • Limited space. Consider a select component if you don’t have enough space to list out all available options.
  • Selecting none. If users should be able to select zero of the options or change their mind and unselect an option, consider using checkboxes. You can also choose to add a “none of the above” option to the radio button group instead.

Usability guidance

  • Use the label as a target. Users should be able to select either the text label or the radio button to select or deselect an option.
  • List items vertically. Vertically-listed options are easier to read than those that are listed horizontally. A horizontal layout can make it difficult to tell which label belongs to which radio button.
  • Use adequate spacing. Make sure selections are adequately spaced for touch screens. Consider using the tile variant for larger touch targets.
  • Set default values with caution. Setting a default value can bias a decision, seem pushy, or alienate users who don’t fit your assumptions. Only use a default selection if you have data to back it up.
  • Don’t mix default and tile variants. Pick one implementation and stick with it. When mixed, tiles can appear to indicate a bias or preference toward that option.
  • Use a logical order. Make sure the selection options are organized in a meaningful way, like alphabetical or most-frequent to least-frequent. This helps users easily find the option they’re looking for.

Accessibility guidance

Test the radio buttons component in your own project.

USWDS tested the radio buttons component for accessibility. You should test your implementation, too.

Use radio buttons accessibility tests
  • Customize form controls accessibly. If you customize this component, ensure that it continues to meet the accessibility requirements that apply to all form controls.
  • Use fieldset and legend. Group related radio buttons together with <fieldset> and describe the group with <legend>.
  • Use proper labels and attributes. Each radio button should have a <label>. Associate the two by matching the <label>’s for attribute to the <input>’s id attribute.

Using the radio buttons component

Radio buttons settings

Variable Description
$theme-input-background-color

Background color for radio and checkbox inputs.
$theme-input-tile-border-radius

Tile border radius for rounded corners.
$theme-input-tile-border-width

Tile border thickness.

Radio buttons variants

Variant Description

.usa-radio__input--tile

Input tiles provide a larger interaction area and neatly group the label with the form control for readability. They’re useful in application forms and questionnaires, but may not be recommended when they create clutter on the page.

Accessibility test status

The USWDS team did 10 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
10 10 0 0 0

Overview of recent accessibility test results:

  • Passed: 10
  • Passed with exceptions: 0
  • Conditional: 0
  • Failed: 0

Learn more on the radio buttons accessibility tests page.

Package

  • Package usage: @forward "usa-radio";
  • Dependencies: uswds-fonts, usa-fieldset, usa-legend, usa-input-list

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-09-18 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2821

2023-09-29 3.6.1
  • Accessibility
  • Styles
 No

Updated radio and checkbox tile styling to have lighter borders. More information: uswds#5494

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved legibility in forced colors mode. Adds a consistent border in forced colors mode. More information: uswds#5147

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency and visibility of disabled styles. Form elements with the disabled or aria-disabled attribute now get consistent styling and have proper color contrast. More information: uswds#5063

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency of disabled styles in forced colors mode. More information: uswds#5295

2022-08-05 3.1.0
No

Styled aria-disabled to match disabled. Now disabled styling is applied whether you use disabled (disabled and hidden from screen readers) or aria-disabled (disabled and visible to screen readers). More information: uswds#4783

2022-04-28 N/A
  • Guidance
 No

Updated package name to usa-radio. More information: uswds-site#1538

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2022-04-13 N/A
  • Guidance
 No

Updated package name to form-controls. More information: uswds-site#1497

2022-04-11 2.13.3
  • Accessibility
  • Styles
 No

Added support for forced colors mode. All our components now support proper display when users have a forced colors mode set in their operating system. More information: uswds#4610

2021-08-18 2.12.1
  • Styles
 No

Improved whitespace sensitivity of radio and checkbox tiles. Now radio and checkbox tiles will display consistently whether or not there’s extra whitespace in the markup. More information: uswds#4286

2021-08-18 2.12.1
  • Styles
 No

Improved class order sensitivity for checkbox and radio. Now checkbox and radio components display properly regardless of the order of the class and modifier names. More information: uswds#4262

2021-06-16 2.12.0
  • Accessibility
  • Styles
 No

Updated checkbox and radio buttons to include automatic accessible color. Now checkbox and radio buttons will display in the proper accessible color, and adapt to the text, link, and background colors you set in your projects’s settings. More information: uswds#4199

2021-06-16 2.12.0
  • Styles
 No

Updated margins in radio tiles. Now radio tiles have cleaner, more reliable styling for their margin. More information: uswds#4181

2021-04-28 2.11.2
  • Styles
 No

Updated checked radio buttons to remain checked in disabled state. Now the visual checked state of a checked checkbox does not change if that element is later disabled. More information: uswds#4160

2021-03-17 2.11.0
  • JavaScript
  • Styles
 No

Fixed character display in checkboxes and radio buttons. Allowed checkboxes and radio buttons to display properly regardless of character encoding. More information: uswds#4080