Radio group

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

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

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.

Settings and Filters

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.


1Field LabelThe 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 choicesno
2Radio input (unchecked)This unmarked state signifies that no option within the associated group has been selected by the user
3Radio 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
4LabelThe label explains the purpose or meaning of the radio button and helps users understand the available choices.yes
5Radio groupsThe 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


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.


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.


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.

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.
LabeltextPositions 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.


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.


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.

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

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.


customValiditycustom-validitystring | undefinedThe error message to display when the control is invalid.
dirty-booleanfalseA control is dirty if the user has changed the value in the UI.
disableddisabledboolean | undefinedWhether the group is disabled; when set no interaction is possible.
form-HTMLFormElement | nullThe form associated with the control.
formValue-unknownThe value used when submitting the form.
horizontalhorizontalboolean | undefinedThe orientation of the radio options; when true, the radio buttons are displayed next to each other instead of below each other.
labels-`NodeListOf<HTMLLabelElement>` | nullThe labels associated with the control.
namenamestring | undefinedThe name of the form control.
nativeFormValue-FormValueReturns the form value as used in a native `<form>`. This is always a string, File, FormData or null.
requiredrequiredboolean | undefinedWhether the user is required to select an option in the group.
showValidshow-validbooleanfalseWhen set will cause the control to show it is valid after reportValidity is called.
showValidityshow-validity'valid' | 'invalid' | undefinedWhether to show the validity state.
sizesize'md' | 'lg' | undefinedThe size of the radio buttons in the group.
touched-booleanfalseA control is marked touched once the user has triggered a blur event on it.
valid-booleanReturns whether the form control is valid or not.
validationMessage-stringString 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-ValidityStateReturns the validity state the control is in.
validityState-'valid' | 'invalid' | 'pending'Returns the current validity state.
valuevalueunknown | undefinedThe value for the radio group, to be used in forms.


reportValiditybooleanReturns 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.
getLocalizedValidationMessagestringThis 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.
setCustomValiditymessage: string | Promise<string>voidSets 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.


NameEvent typeDescription
sl-blurSlBlurEventEmits when the component loses focus.
sl-changeSlChangeEvent<T | undefined>Emits when the value changes.
sl-focusSlFocusEventEmits when the component receives focus.
sl-form-controlSlFormControlEventEmits when the form control is added to the DOM.
sl-update-stateSlUpdateStateEventEmits when the UI state (dirty, pristine, touched or untouched) of the form control changes.
sl-update-validitySlUpdateValidityEventEmits when the validity of the form control changes.
sl-validateSlValidateEventEmits when the form control can be validated.


defaultA 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).


checkedcheckedboolean | undefinedWhether the radio button is checked.
disableddisabledboolean | undefinedWhether this radio button is disabled.
showValidityshow-validity'valid' | 'invalid' |Indicates if the radio button shows it is (in)valid.
sizesize'md' | 'lg''md'The size of the radio button.
valuevalueT | undefinedThe 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.


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.


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:


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:


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.


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.

TabShifts 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/EnterSelects the currently focused option
Arrow KeysOnce 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 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

AttributeValueDescriptionUser supplied
role'radiogroup'Makes it clear that our custom component is a radio groupno
aria-labelledbystringWhen different element serves as the label this property can be set to the id of that elementyes
aria-describedbystringWhen the radio group needs extra explanation or description you can reference this element here by the id. See [Note 1] below for more explanationyes
aria-disabledbooleanAnnounces the radio group as disabled with a screenreader. See [Note 2] below for more explanationyes

Radio Button

AttributeValueDescriptionUser supplied
role'radio'Makes it clear that our custom component is a radio buttonno
aria-checked'true','false'The state of the radio
aria-labelledbystringWhen different element serves as the label this property can be set to the id of that elementyes
aria-labelstringTo be used when you don't have a text label because you want to use images as the options for exampleyes
aria-describedbystringWhen the option needs extra explanation or description you can reference this element here by the id. See [Note 1] below for more explanationyes
aria-disabledbooleanAnnounces the option as disabled with a screenreader. See [Note 2] below for more explanationyes


  1. 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.

  2. 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