Radio group

Radio group is a component used to make single choice from multiple options.

Usage

Code

Accessibility

Dog

Cat

Hamster

<sl-form-field label="Which animal do you like best?">
  <sl-radio-group value="cat">
    <sl-radio value="dog">Dog</sl-radio>
    <sl-radio value="cat">Cat</sl-radio>
    <sl-radio value="hamster">Hamster</sl-radio>
  </sl-radio-group> 
</sl-form-field>

When to use

Radio buttons are best used in situations where users need to make a single selection from multiple options within a defined group. Here are two common scenarios:

In forms

Radio buttons are commonly used in forms where users need to choose one option from a list, such as selecting a gender, indicating a preference, or specifying a category.

They are also valuable for transitioning between settings within menus, pages, or components. Radio buttons help users make exclusive choices when configuring preferences or filtering content, ensuring a clear and structured user experience. Additionally, radio buttons can be applied to various interfaces, including tiles, data tables, modals, and side panels, making them versatile tools for improving user interactions and decision-making.

When not to use

While radio buttons are a valuable UI element in many situations, there are instances when it's best to avoid using them:

When Multiple Selections Are Allowed

Radio buttons are intended for exclusive single-choice selection. If your design requires users to select multiple options from a list simultaneously, checkboxes are more appropriate.

For Large Lists

Radio buttons become less practical as the number of options in a list grows. If you have an extensive list of choices, consider alternative UI components like dropdown menus or autocomplete fields to prevent clutter and maintain a cleaner user experience.

Anatomy

Item	Name	Description	Optional
1	Field Label	The group label, positioned at the top of a radio group, explains the purpose or meaning of the radio buttons and helps users understand the available choices	no
2	Radio input (unchecked)	This unmarked state signifies that no option within the associated group has been selected by the user yet.	no
3	Radio input (checked)	This marked state indicates that the user has selected a specific option from a group of choices presented in the associated radio button set.	no
4	Label	The label explains the purpose or meaning of the radio button and helps users understand the available choices.	yes
5	Radio groups	The radio groups can be displayed with one option, allowing a maximum of five selections. When the list of choices exceeds the limit, it's advisable to consider alternative design solutions like a dropdown menu or combobox. These options provide a more user-friendly way to navigate and select from more extensive choices.	yes

Sizing

Radio Group come in two sizes, to match diferents scenarios:

Medium: The medium-sized radio buttons function as the default option across our user interfaces. It achieves a balanced blend of size and clarity, establishing itself as the standard and user-friendly choice for single-choice.
Large: Opting for the large radio buttons for touch-based devices can offer advantages since it presents a larger tap target. This size facilitates more accessible user interactions.

Status

Radio Group come in two sizes, to match diferents scenarios:

Checked: The checked status signifies that a user has actively selected that option from a group of choices. It visually indicates the chosen state, this visual cue helps users easily identify which option they have selected among the available choices.
Unchecked: An unchecked radio button represents a state where the user has not selected that option. Users can choose only one option at a time in a group of radio buttons. Users can click on an unchecked radio button to select it, deselecting any chosen previously option within the same group.

Variants

Radio Group come in various versions, each suited for specific situations:

Default: The default radio button variant allows users to check or uncheck an option. When a radio button is checked, it indicates that the option is chosen, while when it's unchecked, it means the option is not chosen.
Valid: The valid variant of a radio button functions as a feedback mechanism, confirming that the chosen option aligns with the correct choice according to established criteria.
Invalid: This variant is featured in validation processes. When checked, it communicates issues or discrepancies in the entered data, encouraging users to review and change their input, ensuring data accuracy and a smooth user experience.

Figma Options

With these options, you can tweak the appearance of the radio group in Figma. They are available in the Design Panel so you can compose the component to exactly fit the user experience need for the use case you are working on.

Item	Options	Description
Size	`'medium', 'large'`	The button is available in three sizes. If not specified the default value is `medium` .
Variant	`'default', 'valid', 'invalid'`	The button offers four distinct intents: Default, Primary, Success, Warning, and Danger, each conveying a unique tone to the user.
State	`'idle', 'hover', 'active', 'disabled'`.	There are four button types to choose from so you can differentiate between buttons, depending on how essential they are.
Status	`'checked', 'unchecked'`	Elevate your buttons by including icons either before (start) or after (end) the label for enhanced functionality and visual impact.
Label	`text`	Positions the label to the right (at the end) of the radio to provide contextual information.
Focus ring	`'on', 'off'`	Turn the focus ring option to show the focus state of the checkbox.

Behavior

Let's explore the behavior of the radio button:

Label overflow wrap

When a label is too long for the available horizontal space, it wraps to form another line, with the text aligned to the top.

Clickable area

The radio has a clickable area around both the checkbox and label for more space to press. We've left a bit of space on the left side to ensure smooth alignment and avoid any unexpected layout issues.

Focusable area

Both the radio input and label are interactive elements, allowing users to interact with them. However, when it comes to focusing, whether through keyboard navigation or voice commands, the visible focus state is only visible on the checkbox itself.

Validation

If an issue arises after submitting a form, the radio button and the help text will switch to an 'invalid' state. This serves as a valuable guide for users, clearly explaining the necessary actions to resolve any problems.

Exclusive selection

When a user selects one radio button within a group, it becomes the dominant choice, and all other options within the group immediately fade into the background, visually and functionally. This creates a clean and intuitive way for users to make a single, exclusive selection from a list of options.

Default checked

You have the power to decide the radio button's fate from the start! You can set it to be initially checked or unchecked by default, giving you control (or not) over its state.

Dog

Cat

Hamster

<sl-form-field label="Which animal do you like best?">
  <sl-radio-group value="cat">
    <sl-radio value="dog">Dog</sl-radio>
    <sl-radio value="cat">Cat</sl-radio>
    <sl-radio value="hamster">Hamster</sl-radio>
  </sl-radio-group> 
</sl-form-field>

Radio group API

Radio group is the wrapper for the radiobuttons that represent the options for one value in your form. Per radio-group you can only check one radio button.

Properties

Name	Attribute	Type	Default	Description
`customValidity`	`custom-validity`	`string \| undefined`		The error message to display when the control is invalid.
`dirty`	-	`boolean`	`false`	A control is dirty if the user has changed the value in the UI.
`disabled`	`disabled`	`boolean \| undefined`		Whether the group is disabled; when set no interaction is possible.
`form`	-	`HTMLFormElement \| null`		The form associated with the control.
`formValue`	-	`unknown`		The value used when submitting the form.
`horizontal`	`horizontal`	`boolean \| undefined`		The orientation of the radio options; when true, the radio buttons are displayed next to each other instead of below each other.
`labels`	-	`NodeListOf<HTMLLabelElement>` \| null		The labels associated with the control.
`name`	`name`	`string \| undefined`		The name of the form control.
`nativeFormValue`	-	`FormValue`		Returns the form value as used in a native `<form>`. This is always a string, File, FormData or null.
`required`	`required`	`boolean \| undefined`		Whether the user is required to select an option in the group.
`showValid`	`show-valid`	`boolean`	`false`	When set will cause the control to show it is valid after reportValidity is called.
`showValidity`	`show-validity`	`'valid' \| 'invalid' \| undefined`		Whether to show the validity state.
`size`	`size`	`'md' \| 'lg' \| undefined`		The size of the radio buttons in the group.
`touched`	-	`boolean`	`false`	A control is marked touched once the user has triggered a blur event on it.
`valid`	-	`boolean`		Returns whether the form control is valid or not.
`validationMessage`	-	`string`		String representing a localized (by the browser) message that describes the validation constraints that the control does not satisfy (if any). The string is empty if the control is not a candidate for constraint validation, or it satisfies its constraints. For true localization, see `getLocalizedValidationMessage()` instead.
`validity`	-	`ValidityState`		Returns the validity state the control is in.
`validityState`	-	`'valid' \| 'invalid' \| 'pending'`		Returns the current validity state.
`value`	`value`	`unknown \| undefined`		The value for the radio group, to be used in forms.

Methods

Name	Parameters	Return	Description
`focus`		`void`
`reportValidity`		`boolean`	Returns whether the control is valid. If the control is invalid, calling this will also cause an `invalid` event to be dispatched. After calling this, the control will also report the validity to the user.
`getLocalizedValidationMessage`		`string`	This returns a localized validation message. It does not support all `ValidityState` properties, since some require more context than we have here. If you need to support more, you can override this method in your own form control.
`setCustomValidity`	`message: string \| Promise<string>`	`void`	Sets a custom validation message for the form control. If the message is not an empty string, that will make the control invalid. By setting it to an empty string again, you can make the control valid again.

Events

Name	Event type	Description
`sl-blur`	`SlBlurEvent`	Emits when the component loses focus.
`sl-change`	`SlChangeEvent<T \| undefined>`	Emits when the value changes.
`sl-focus`	`SlFocusEvent`	Emits when the component receives focus.
`sl-form-control`	`SlFormControlEvent`	Emits when the form control is added to the DOM.
`sl-update-state`	`SlUpdateStateEvent`	Emits when the UI state (dirty, pristine, touched or untouched) of the form control changes.
`sl-update-validity`	`SlUpdateValidityEvent`	Emits when the validity of the form control changes.
`sl-validate`	`SlValidateEvent`	Emits when the form control can be validated.

Slots

Name	Description
`default`	A list of `sl-radio` elements.

Radio API

The radio button is a single button that can either be selected or deselected (by picking another option in the same radio-group).

Properties

Name	Attribute	Type	Default	Description
`checked`	`checked`	`boolean \| undefined`		Whether the radio button is checked.
`disabled`	`disabled`	`boolean \| undefined`		Whether this radio button is disabled.
`showValidity`	`show-validity`	`'valid' \| 'invalid' \|`		Indicates if the radio button shows it is (in)valid.
`size`	`size`	`'md' \| 'lg'`	`'md'`	The size of the radio button.
`value`	`value`	`T \| undefined`		The value for this radio button.

Having an accessible application is not only achieved by writing good code, but also (maybe even MORE so) by writing good copy. To make sure radio groups and their options are clear for all users make sure to keep these points in mind:

Radio Group labels

A group label of a radio group is a descriptive element that provides context and identifies a collection of radio buttons that are related or belong to the same category or set.

By following the tips below, you can write group labels that effectively categorize radios.

Conciseness

Keep the label concise. Use as few words as possible while still conveying the primary purpose or theme of the options in the group.

Descriptive Clarity

While being concise, ensure the label provides enough information to make it clear what the options within the group represent. Use descriptive language that leaves no ambiguity.

User-Centered Language

Use language that your target audience can easily understand. Avoid complex terminology or jargon that might confuse users.

Consistency

Maintain a consistent style and wording for group labels throughout your interface. This creates a cohesive design and makes it easier for users to understand the organization.

Radio button labels

The primary purpose of the label is to provide context, explanation, or information about the choice represented by the radio button. Labels help users understand the meaning of the radio button and the choices available. Follow these tips for creating clear and user-friendly radio labels:

Conciseness:

Keep the label concise. Use as few words as necessary to convey the radio's primary purpose or action.

Descriptive Clarity

While being concise, ensure the label provides enough information to make it clear what the radio represents or the action it triggers. Use descriptive language that leaves no room for ambiguity.

User-Centered Language

Use language that your target audience can easily understand. Avoid using technical jargon or industry-specific terms that might confuse users.

Sorting Options

When presenting checkboxes in a group, consider sorting them logically. You can arrange them alphabetically or by importance.

Help text

Positioned beneath radio groups, help text offers valuable context and guidance. Follow these tips to craft informative and user-friendly help text:

Conciseness

Keep the help text brief, using only 1-2 short, complete sentences. Avoid unnecessary verbosity to maintain clarity.

Descriptive Clarity

While being concise, ensure the help text provides clear and informative guidance. Explain what happens when the user selects the option, ensuring they understand the consequences or benefits associated with their choice.

User-Centered Language

Use language that aligns with your target audience. Avoid technical jargon or industry-specific terms that might confuse users.

No Repetition

Avoid merely restating the label in different phrasing within your help text. Instead, focus on providing additional context and information that enhances the user's understanding.

Consistency

Maintain a consistent style and tone throughout your help text. This consistency aids users in understanding and interacting with your interface.

Focus order

The focus order of a radio button group determines the sequence in which keyboard or accessibility device users can navigate and select options within the group. It ensures a logical and consistent flow of focus, enabling users to make choices in an organized manner while adhering to accessibility standards.

Keyboard interactions

Keyboard interactions within a radio button group allow users to navigate options using arrow keys or the Tab key, facilitating efficient selection and ensuring accessibility for those who rely on keyboard navigation. Typically, users can navigate to a radio group using the "Tab" key, once they're in the group they can focus the different options with Arrow keys. Then they can select an option with the "Spacebar" or "Enter" key. Keyboard interaction ensures that individuals who rely on keyboard navigation or assistive technologies can easily control checkboxes within a user interface. We use tab to switch between groups and "skip" the separate options in the tab-flow to enable faster navigation in a form; when you want to navigate to the "Save" button quickly, you shouldn't be required to go over the complete list of options just to get to the end of the form.

Key	Description
Tab	Shifts focus to the first radio option in a radio group. Or when a radio button is focused the focus will go the the next focusable element in the page when the tab key is pressed
Space/Enter	Selects the currently focused option
Arrow Keys	Once you are "in" a radio group you can navigate to the next option by using the right or down arrow key. You can navigate back to the previous box with left or up. The focus indicator loops, so when you are at the last option and press "down" it will focus the first option.

WAI-ARIA

WAI-ARIA Roles, States, and Properties for radio buttons and groups provide essential information to assistive technologies and screen readers. They convey the radio button's role, state (checked, unchecked, valid and invalid), and additional properties to ensure accessibility and a better user experience for individuals using assistive technology.

Specifies whether the attribute is always set in the component (no) or it needs to be provided by the developer (yes)

Radio Group

Attribute	Value	Description	User supplied
`role`	`'radiogroup'`	Makes it clear that our custom component is a radio group	no
`aria-labelledby`	string	When different element serves as the label this property can be set to the `id` of that element	yes
`aria-describedby`	string	When the radio group needs extra explanation or description you can reference this element here by the `id`. See [Note 1] below for more explanation	yes
`aria-disabled`	boolean	Announces the radio group as disabled with a screenreader. See [Note 2] below for more explanation	yes

Radio Button

Attribute	Value	Description	User supplied
`role`	`'radio'`	Makes it clear that our custom component is a radio button	no
`aria-checked`	`'true','false'`	The state of the radio button.	no
`aria-labelledby`	string	When different element serves as the label this property can be set to the `id` of that element	yes
`aria-label`	string	To be used when you don't have a text label because you want to use images as the options for example	yes
`aria-describedby`	string	When the option needs extra explanation or description you can reference this element here by the `id`. See [Note 1] below for more explanation	yes
`aria-disabled`	boolean	Announces the option as disabled with a screenreader. See [Note 2] below for more explanation	yes

Notes:

There is a subtle difference between aria-labelledby and aria-describedby; a label should be concise, where a description is intended to provide more verbose information. A description for a radio group can for example be used to explain what (delayed) effect a the chosen option will have. Or in the case of an option you can use it for example for an option with a value of "other..." so you can direct the user to a textfield where they can leave their own option.
The aria-disabled should not be used as a one-for-one replacement for the disabled attribute because they have different functionalities:
- disabled dims the button visually, takes it out of the tab-focus sequence, prevents actions (click, enter) on it and anounces it as 'dimmed' or 'disabled' in a screenreader.
- aria-disabled only does the latter. You will need to disable the functionality yourself. This might be useful for scenario's where you don't want to take the button out of the navigation flow.
When disabled is added to an element there is no need to also add aria-disabled; Everything aria-disabled does, disabled does as well.
You can read more on the difference and in which scenarios which option might be preferable on the MDN page about aria-disabled

Interactive example