Skip to content
+

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.

Press Enter to start editing

Customization

Variants

The Radio component supports Joy UI's four global variants: outlined (default), soft , solid , and plain.

Press Enter to start editing

Sizes

The Radio component comes in three sizes: sm, md (default), and lg:

Press Enter to start editing

Colors

Every palette included in the theme is available via the color prop.

Press Enter to start editing

Label

Use the label prop to add a label to a Radio button.

Press Enter to start editing

For more complex layouts, compose a Radio button with Form Control, Form Label, and Form Helper Text (optional), as shown below:

One line description maximum lorem ipsum
Press Enter to start editing

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.

Helper text for this radio.
This is helper text.
Press Enter to start editing

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:

Press Enter to start editing

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

Select an option and use keyboard ↑↓ to see the focus outline
Press Enter to start editing

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.

For light background jobs like sending email
For tasks like image resizing, exporting PDFs, etc.
For intensive tasks like video encoding, etc.

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/or title, directly on the input component. You can also use the slotProps.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.