Components

Radio button

Use: Deployed English, Spanish, Tagalog

USWDS v3

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

Examples - v3

Examples - v1

Default

View va-radio v1 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.

Conditionally revealed fields

In the radio button and checkbox components, we offer an option to conditionally reveal fields when the user selects an answer. These fields are often used to group related questions together by revealing a single follow-up question only when they’re relevant to the user.

Conditionally revealed fields can be used if the following conditions are met:

There should only be one reveal on a page.
When the revealed trigger is selected, you must be able to tab directly into the newly revealed field (Which is why we’ve put the “other” question last.)
The newly revealed question field must be understood by itself. For example, don’t just say “Other”. Instead, say:

Since your relationship with the veteran was not listed, please describe it here

An example of a conditionally revealed field — Example of asking the relationship to the Veteran with radio buttons and a conditionally revealed field.

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`	`true`	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

Radio button

Examples - v3

Default

Tile

Hint text

Label header

On background

Forms pattern single

Forms pattern multiple

Error

Forms pattern single error

Internationalization

Examples - v1

Default

Usage

Choosing between variations

Conditionally revealed fields

Errors

Code usage

Attributes and Properties

Events

Accessibility considerations