Skip to main content
U.S. flag

An official website of the United States government

Components

Radio button

Use: Best practice English, Spanish, Tagalog USWDS v3
Radio buttons allow users to select exactly one choice from a group.

Examples

Default

View va-radio in Storybook

Tile

View va-radio tile in Storybook

Hint text

View va-radio with hint text in Storybook

Label header

View va-radio with label header in Storybook

On background

View va-radio on background in Storybook

Forms pattern single

View va-radio forms pattern single in Storybook

Forms pattern multiple

View va-radio forms pattern multiple in Storybook

Error

View va-radio error in Storybook

Forms pattern single error

View va-radio forms pattern single error in Storybook

Internationalization

View va-radio internationalization in Storybook

Usage

Choosing the right component for the task

When deciding which component to use, consider the number of options available to the user. The total number of options will determine which component is right for the task:

  • 2 - 5 options: Use Radio button when there are only a few options that can all be exposed at once.
  • 6 - 15 options: Use Select for a limited number of options.
  • 16 - 100 options: Use Combo box, which combines a select with typeahead functionality for easier selection.
  • 101+ options: Use Search input with typeahead to help users quickly find the right option from a large set.

Exceptions to consider when choosing a component

In some cases, exceptions may be considered when choosing the right component:

  • When the options are known and memorable. Use Combo box if the user will know what to expect as options in the dropdown, such as a list of countries or states. See the USWDS address pattern.
  • When the radio button labels are long or radio tiles contain descriptive text. Long labels within a dropdown might make it difficult to read and select an option. Radio tiles often include descriptive text that cannot be used in a dropdown. In these cases, Radio button may be the better choice.

Contact the Design System team via #platform-design-system for help if you have other use cases that may be considered exceptions.

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:

  1. There should only be one reveal on a page.
  2. 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.)
  3. 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

  • Refer to the specific error examples above.

Hint text

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` is true. formHeadingLevel form-heading-level number 3 The heading level for the heading if `useFormsPattern` is 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) messageAriaDescribedby message-aria-describedby string An optional message that will be read by screen readers when a radio option is focused. 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 PropertyAttributeTypeDefaultDescriptionenableAnalyticsenable-analyticsbooleanfalseWhether or not an analytics event will be fired.errorerrorstringA string with an error message.formHeadingform-headingstringThe content of the heading if `useFormsPattern` is true.formHeadingLevelform-heading-levelnumber3The heading level for the heading if `useFormsPattern` is true.headerAriaDescribedbyheader-aria-describedbystringAn 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.hinthintstringOptional hint text.labellabelstringThe text label for the radio group.labelHeaderLevellabel-header-levelstringInsert a header with defined level inside the label (legend)messageAriaDescribedbymessage-aria-describedbystringAn optional message that will be read by screen readers when a radio option is focused.requiredrequiredbooleanfalseWhether or not this input field is required.useFormsPatternuse-forms-patternstringEnabling 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

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. NameDescriptioncomponent-library-analyticsThe event used to track usage of the component. This is emitted when a radio option is selected and enableAnalytics is true.vaValueChangeThe event emitted when the selected value changeskeydown The event emitted when a key is pressed. radioOptionSelected The event emitted when the selected option value changes.

Content considerations

Accessibility considerations

Additional accessibility considerations for VA

  • When using Safari with VoiceOver, it will read out the fieldset legend for each radio item when navigating through them. However, the recommended behavior is that the legend should only be read out at the end of the first radio option when tabbing into the group. This behaves as expected in other browsers with VoiceOver, but Safari does not support this. There currently is no workaround for this.
Edit this page in GitHub (Permissions required)
Last updated: Mar 21, 2025