Skip to content
Skip to content

Radio Group

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

Introduction

The Radio component is the one to be used when you want to allow users to select only one option at a time. To allow multiple selection, use the Checkbox instead. For more in-depth about when to use each, visit the NNg's documentation.

<Radio />

Playground

Component

After installation, you can start building with this component using the following basic elements:

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

export default function MyApp() {
  return (
    <Box>
      <Radio value="Hello World" name="radio-buttons" />
    </Box>
  );
}

Basic usage

The Radio component supports every Joy UI global variant and it comes with outlined set as the default one.

Label

Use label prop to label the radio buttons.

For complex layout, compose a radio button with FormControl, FormLabel, and FormHelperText (optional).

One line description maximum lorem ipsum

Position

To swap the label and radio position, use the CSS property flex-direction: row-reverse.

Radio group

The RadioGrop component is the ideal wrapper for multiple Radio components as it provides a tailored API for radio button grouping and proper keyboard-navigation accessibility support.

A helper text for this radio.
This is a helper text.

Controlled

To control what the radio button is selecting, use the value and onChange props.

Focus outline

The focus outline, by default, wraps both the radio itself and its label. To change that, target the radioClasses.radio class and add position: 'relative'.

Select an option and use keyboard ↑↓ to see the focus outline

Overlay

To make the whole container in which the radio button is in clickable, use the overlay prop.

You can also use it directly in the RadioGroup component as it will automatically be forwarded to every individual radio button inside of it.

Icon

Radio, by default, comes without an unchecked component. To add an icon to both unchecked and checked states, use the uncheckedIcon and checkedIcon props.

Without an icon

To communicate the checked and unchecked states with different artifacts, such as border or background color, use the disableIcon prop to remove the default icon.

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 FormControl and FormLabel 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 inputProps prop to add them.
<Radio
  value="radioA"
  slotProps={{
    input: {
      'aria-label': 'Radio A',
    },
  }}
/>

Visit the WAI-ARIA documentation for more details.

Common examples

Segmented controls

Justify:

Tiers

A clone of an inspiration that demonstrate the composition of the components.

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

Alignment buttons

Provide an icon as a label to the Radio to make the radio buttons concise. You need to provide aria-label to the input slot for users who rely on screen readers.

Payment methods

Mix radio buttons with the List-related components to create a commonly seen 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 radios. 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 that we don't need to handpick a color that has enough contrast with the background.


API

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