Components
Radio button
Use: Deployed English, Spanish, Tagalog
Radio buttons allow users to see all available choices at once and select exactly one option.
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 ofusa-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.
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>
’sfor
attribute to the<input>
’sid
attribute.