Components

Radio button

Use: Deployed English, Spanish, Tagalog

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 Radio Button errorMessage

option 1

option 2

option 3 label

<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.
`hint`	`hint`	`string`		Optional hint text.
`label`	`label`	`string`		The text label for the radio group.
`required`	`required`	`boolean`	`false`	Whether or not this input field is required.
`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

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.