Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Components

Radio Button

Use: Deployed
Radio buttons allow users to see all available choices at once and select exactly one option.

View va-radio in Storybook

Usage

When to use radio buttons

  • When users need to select only one option out of a set of mutually exclusive choices.
  • When the number of available options can fit onto a mobile screen.

When to consider something else

  • Consider checkboxes if users need to select more than one option or if there is only one item to select.
  • Consider a dropdown if you don’t have enough space to list out all available options.
  • If users should be able to select zero of the options.

How to use

  • Users should be able to tap on or click on either the text “label” or the radio button to select or deselect an option.
  • Options that are listed vertically are easier to read than those that are listed horizontally. Horizontal listings can make it difficult to tell which label pertains to which radio button.
  • If you customize, make sure selections are adequately spaced for touch screens.
  • Use caution if you decide to set a default value. Setting a default value can discourage users from making conscious decisions, seem pushy, or alienate users who don’t fit into your assumptions. If you are unsure, leave nothing selected by default.

Errors

  • Radio buttons typically appear inside of <fieldset>s. The class name of usa-input-error may be placed on the <fieldset> that contains all of the radio buttons.
  • The error message is placed just below the <legend>.
  • See form error handling for additional guidance.
Radio Buttons Error Radio Button errorMessage
<fieldset class="fieldset-input usa-input-error">
  <legend class="legend-label usa-input-error-label">Radio Buttons</legend>
  <span class="usa-input-error-message" role="alert" id="defaultId-error-message">
    <span class="sr-only">Error</span> Radio Button errorMessage</span>
  <div class="form-radio-buttons">
    <div class="radio-button">
      <input type="radio" autocomplete="false" id="defaultId-0" name="defaultName" value="option 1" />
      <label name="defaultName-0-label" for="defaultId-0">option 1</label>
    </div>
  </div>
  <div class="form-radio-buttons">
    <div class="radio-button">
      <input type="radio" autocomplete="false" checked="" id="defaultId-1" name="defaultName" value="option 2" />
      <label name="defaultName-1-label" for="defaultId-1">option 2</label>
    </div>
  </div>
  <div class="form-expanding-group">
    <div class="form-radio-buttons">
      <div class="radio-button">
        <input type="radio" autocomplete="false" id="defaultId-2" name="defaultName" value="expanding option 3" />
        <label name="defaultName-2-label" for="defaultId-2">option 3 label</label>
      </div>
    </div>
  </div>
</fieldset>

Code usage

Attributes and Properties

Property Attribute Type Default Description
enableAnalytics enable-analytics boolean false Whether or not an analytics event will be fired.
error error string A string with an error message.
label label string The text label for the radio group.
required required boolean false Whether or not this input field is required.

Events

Name Description
component-library-analytics The event used to track usage of the component. This is emitted when a radio option is selected and enableAnalytics is true.
vaValueChange The event emitted when the selected value changes
keydown The event emitted when a key is pressed.
radioOptionSelected The event emitted when the selected option value changes.

Accessibility considerations

  • Group related radio buttons together with <fieldset> and describe the group with <legend>.
  • Each radio button should have a <label>. Associate the two by matching the <label>’s for attribute to the <input>’s id attribute.
  • The title attribute can replace <label>.
Edit this page in GitHub (Permissions required)
Last updated: Jun 14, 2022