Component Radio Button

A radio button is used to select a single option from a list of choices. It's used with the radio button group component.

Get the UI kit

Code

Usage

Example

Choose your favorite color

Red

Green

Blue

Props

Attr	Type	Default	Docs
checked	boolean	false	This property is used to set the radio button as "checked".
disabled	boolean	false	This boolean is used to set the radio button as disabled.
hide-label	boolean	false	This property will visually hide the label. A label is still required to be provided for screenreader support.
input-aria-label	string	null	This property can be used to set the ARIA label associated with this input (for screen readers).
input-id	string	generateId('som-radio-button')	This property can be used to specifically set an ID to the input field. If an ID is not provided, it will be dynamically generated.
label	string	''	This property is the radio button label text.
label-class	string	''	This property is a list of CSS classes that can be used to style the label.
name	string	''	This property is the form element name (used when submitting the form).
required	boolean	false	This boolean can be used to set the input as required.
value	string	''	This property is the radio button value sent on submit when using it in a form.

Methods

Name	Returns	Docs
setFocus	Promise will resolve after focus.	This public method sets focus to the radio element.

Events

Event	Detail	Docs
somBlur	any	This event is emitted when when the radio button loses focus.
somChange	any	This event is emitted when the radio button is toggled.
somFocus	any	This event is emitted when when the radio button gets focus.

Slots

Name	Docs
label	Label for the radio button. Alternatively, you can use the label attribute.

Anatomy

A dissection of the various parts of a radio button group labeled below.

Group label: Identifies the radio button group.
Radio button: A single option in a radio button group.
Radio button input: Shows the radio button’s selection status.
Radio button label: Text describing the radio button value.
Helper text: Provides additional context if needed.
Radio button group: A collection of radio buttons as options in a field.

Labels

Each field needs a clear and short label.
Labels don’t require punctuation at the end.
If used, punctuation should be consistent across all labels.
Labels should use sentence style capitalization.
Labels don’t need to be complete sentences.

A group label above a radio button group, as described in the caption.

Always use a group label when using a radio button group.

A radio button group lacking a group label, as described in the caption.

Failing to add a group label can confuse users as to what the selections represent.

Helper and error text

Use helper text to clarify requirements for making selections.
Use error text to explain user mistakes. Error text should be specific enough to correct errors.
Use sentence case, write full sentences, and use punctuation.
Helper text will appear underneath a field, except when an error message replaces it.

Helper text below a radio button group and error text below another radio button group, as described in the caption. — The leftmost radio button group has helper text that helps the user complete the field. The rightmost radio button group has error text to help correct an error.

Required and optional

Establish whether a radio button group needs to have a selection made or not by marking them accordingly. Optional radio button groups are marked “(optional)” after the group label, and required radio button groups have a red asterisk after the group label.

By default, fields not marked as required will show optional indicators. To display indicators for required fields instead, you can manually override this behavior by passing the props as shown in the code section.

Radio button groups that are required will have a red asterisk at the end of their group label. Ones that aren’t will have (optional) at the end of their group label.

Tooltips

You can add a tooltip to a radio button group label by setting the tooltip attribute to the desired text. Note that individual radio buttons cannot have tooltips.

Use tooltips sparingly, and keep text brief and supplementary. Do not include interactive elements. The tooltip appears on hover or keyboard focus.

Select your favorite color

Green

Pink

Navy

How to use

Radio buttons allow users to make a selection from a list of options. Once selected, a radio button cannot be deselected without choosing another option. Use a radio button group if:

Users may only make a single selection.
The list of options is short enough to be displayed at once.
It's important for users to see all options at once.

Radio button or checkbox?

Checkboxes are visually similar to radio buttons but have different uses. Use a checkbox or checkbox group instead if:

Users can make more than one selection.
Users should be able to uncheck a selection.
Users are acknowledging or affirming a statement.

A checkbox group with more than one option selected.

Use a checkbox group when more than one option can be selected.

A radio button group limiting users to a single option, as described in the caption.

Don’t use radio button groups if users can make multiple selections.

Radio button group or select?

Like radio button groups, selects allow users to make single selections from a list. Use a select instead if:

There are more than five options to choose from.
Displaying all options would take up too much space.
It's not necessary for all options to always be visible.

A select showing multiple preset options, as described in the caption.

Use a select when there are multiple preset options.

A radio button group used improperly to show eight options.

Avoid using radio button groups if there are more than five options.

Behavior

States

A radio button can be selected or unselected, unless it’s disabled. Depending on the state, the mouse pointer may shift to a different icon.

The default, hover, active, focus, and disabled radio button states, as described in the caption. — Button states communicate the button’s status to the user.

Default: The standard state of a radio button input control.
Hover: When a user’s cursor moves over a radio button input control without clicking it.
Active: When users press a radio button input control before releasing.
Focus: When a user highlights a radio button input control with a keyboard.
Disabled: An unavailable selection. Be sure that users aren’t confused as to why a radio button input control is disabled. If the user is likely to be confused, keep the radio button input control enabled and trigger a detailed error when it’s clicked, or the form is submitted.

Errors

Error messages appear when users fail to make a required selection. Real-time validation makes filling out forms easier and faster. If that can’t be implemented, validate the radio button group as soon as the user submits the form.

A radio button marked with an error, as described in the caption. — When a user makes an error, a red asterisk appears after the group label and error text appears below the radio button group.

Text wrapping

When a radio button’s label is too long for the available space, it will wrap to form another line. Avoid wrapping text too many lines.

Radio button label text overflowing to the next line, as described in the caption. — Radio button labels wrap when there is not enough space.

Interactions

Mouse

Users can select an option when they click on the radio button or the label. When hovering over a disabled radio button, their cursor indicates that it is not selectable by transforming into the error icon.

Keyboard focus

Users can work with arrow keys to cycle through the individual radio buttons. Unlike with checkbox groups, the Tab key cycles through the different radio button groups.

Layout

By default, radio button groups are arranged vertically. A horizontal variant is available, but should be used sparingly. Horizontal layouts can make it hard for users to connect each radio button with its label.

A vertically aligned radio button group above a horizontally aligned radio button group, which should be used sparingly. — Radio button groups should be aligned vertically when possible.

Get in touch

Do you have an idea, or want to help us improve this page? Reach out to us via email.

DTMB-DG-Support@michigan.gov

Need help? Visit our Support page to learn how to get assistance, troubleshoot issues, and connect with the team.