Radio

Radio buttons enable the user to select one option from a set.

Introduction

Radio buttons let users make a mutually exclusive choice (e.g., 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.

Basics

import Radio from '@mui/joy/Radio';

The Joy UI Radio button behaves similar to the native HTML , 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:

Common examples

Segmented controls

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.

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 documentation for more details.

Anatomy

The Radio Group component is composed of a root <div> element that can wrap multiple Radio components.

<div class="JoyRadioGroup-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="JoyRadio-root">
    <span class="JoyRadio-radio">
      <span class="JoyRadio-icon"></span>
      <span class="JoyRadio-action">
        <input class="JoyRadio-input">
      </span>
    </span>
    <label class="JoyRadio-label">
  </span>

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <Radio />
• <RadioGroup />