Radio
Radio buttons enable the user to select one option from a set.
Introduction
Radio buttons let users make a mutually exclusive choice (for example: "this" or "that"). Only one selection is allowed from the available set of options.
Radio buttons should have the most commonly used option selected by default.
<Radio />
Playground
Basics
import Radio from '@mui/joy/Radio';
The Joy UI Radio button behaves similar to the native HTML <input type="radio">
, so it accepts props like checked
, value
and onChange
.
Customization
Variants
The Radio component supports Joy UI's four global variants: outlined
(default), soft
, solid
, and plain
.
Sizes
The Radio component comes in three sizes: sm
, md
(default), and lg
:
Colors
Every palette included in the theme is available via the color
prop.
Label
Use the label
prop to add a label to a Radio button.
For more complex layouts, compose a Radio button with Form Control, Form Label, and Form Helper Text (optional), as shown below:
Position
To swap the positions of a Radio and its label, use the CSS property flex-direction: row-reverse
.
Usage with Radio Group
import RadioGroup from '@mui/joy/RadioGroup';
The Radio Group component is the ideal wrapper for multiple Radio components as it provides a tailored API for grouping and better keyboard navigation accessibility.
Controlled
Use the value
and onChange
props to control the actions performed by the Radio buttons.
For example, the Radio buttons in the demo below update the state to reflect the selected option:
Focus outline
By default, the focus outline wraps both the Radio button and its label.
If you need to focus to omit the label, target the radioClasses.radio
class and add position: 'relative'
.
Overlay
To make the Radio button's container clickable, use the overlay
prop.
You can also apply this prop directly to a Radio Group when present, which will pass the prop to each individual Radio button nested within.
Custom icons
Use the checkedIcon
and uncheckedIcon
props to add custom icons to the Radio button that correspond to each state, respectively.
The demo below shows how to apply a custom checkedIcon
to the Radio button that sits on the corner of each Sheet:
No icon
Use the disableIcon
prop to remove the Radio button's icon.
In this case, you'll need to use CSS properties like border and background color to communicate the state of the Radio button, as shown in the demo below:
Justify:
Tiers
This example demonstrates the composition of the components, and was inspired by this Dribbble shot from Tailwind Labs.
Alignment buttons
This example uses icons as labels for a group of Radio buttons to recreate the form and function of Toggle Buttons.
In this case, you must provide an aria-label
to the input slot for users who rely on screen readers.
Payment methods
Mix Radio buttons with the List components to create a vertical or horizontal payment method list.
Pay with
E-commerce product attributes
This example demonstrates complex customization using the Sheet component as a container for the Radio buttons. The focus outline is customized to be smaller, and the color changes based on the value.
The check icon's color inherits the Radio button's solid
variant, so you don't need to handpick a color that contrasts enough with the background.
Accessibility
Here are a few tips to make sure you have an accessible Radio button component:
- Every Form Control should have proper labels. This includes Radio buttons, Checkboxes, and Switches. In most cases, this is done by using the Form Control and Form Label element.
- When a label can't be used, make sure to add an attribute, such as
aria-label
,aria-labelledby
, and/ortitle
, directly on the input component. You can also use theslotProps.input
prop to add them.
<Radio
value="radioA"
slotProps={{
input: {
'aria-label': 'Radio A',
},
}}
/>
Visit the WAI-ARIA Authoring Practices for more details.
Anatomy
The Radio Group component is composed of a root <div>
element that can wrap multiple Radio components.
<div class="MuiRadioGroup-root">
<!-- Radio components here -->
</div>
The Radio component is composed of a root <span>
, with further nested <span>
elements for the radio button, icon, action (with a nested <input>
), and its associated <label>
.
<span class="MuiRadio-root">
<span class="MuiRadio-radio">
<span class="MuiRadio-icon"></span>
<span class="MuiRadio-action">
<input class="MuiRadio-input">
</span>
</span>
<label class="MuiRadio-label">
</span>
API
See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.