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 English, Spanish, Tagalog USWDS v3
Radio buttons allow users to select exactly one choice from a group.

Examples - v1

Default

View va-radio in Storybook

Hint text

View va-radio with hint text in Storybook

Label header

View va-radio with label header in Storybook

Description text

View va-radio with description text in Storybook

Tile

View va-radio tile in Storybook

Error

View va-radio error in Storybook

Internationalization

View va-radio internationalization in Storybook

Examples - v3

Default

View va-radio v3 default and additional variations in Storybook

Usage

Refer to the U.S. Web Design System for usage guidance

Choosing between variations

  • Use the Hint text variation to provide additional information that pertains to the question being asked or all of the options presented.
  • Use the Label header variation when a heading is required within the legend that acts as a label for the radio buttons. This can aid users in navigating the form questions, particularly in the sub-task pattern
  • Use the Description text variation to provide additional details about one or more radio button options. This variation is superseded by the Tile variation.
  • Use the Tile variation to provide additional details about one or more radio button options within a large and well defined tap target.

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.
<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.
formHeading form-heading string The content of the heading if `useFormsPattern` and `uswds` are true.
formHeadingLevel form-heading-level number 3 The heading level for the heading if `useFormsPattern` and `uswds` are true.
headerAriaDescribedby header-aria-describedby string An optional message that will be read by screen readers when the header is focused. The label-header-level prop must be set for this to be active.
hint hint string Optional hint text.
label label string The text label for the radio group.
labelHeaderLevel label-header-level string Insert a header with defined level inside the label (legend)
required required boolean false Whether or not this input field is required.
useFormsPattern use-forms-pattern string Enabling this will add a heading and description for integrating into the forms pattern. Accepts `single` or `multiple` to indicate if the form is a single input or will have multiple inputs. `uswds` should be true.
uswds uswds boolean false Whether or not the component will use USWDS v3 styling.

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

Refer to the U.S. Web Design System for accessibility guidance

Edit this page in GitHub (Permissions required)
Last updated: Feb 13, 2024