react-test/docs/data/joy/components/radio-button/radio-button.md

productId, title, components, githubLabel, waiAria

productId	title	components	githubLabel	waiAria
joy-ui	React Radio Button component	Radio, RadioGroup	scope: radio	https://www.w3.org/WAI/ARIA/apg/patterns/radio/

Radio

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

{{"component": "@mui/docs/ComponentLinkHeader"}}

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.

{{"demo": "RadioUsage.js", "hideToolbar": true, "bg": "gradient"}}

:::success When should you use radio buttons rather than checkboxes, switches, or selects?

• Use checkboxes to give the user multiple binary choices—radio buttons are preferable when you need to restrict user selection to one mutually exclusive option from a series.

• Use a switch to provide the user with a single binary choice—radio buttons are preferable when you need to give the user multiple binary choices.

• Consider using a select if it's not important for the user to be able to see all options.

• If available options can be collapsed, consider using a Select component to conserve space.

  :::

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.

{{"demo": "RadioButtons.js"}}

Customization

Variants

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

{{"demo": "RadioVariants.js"}}

:::info To learn how to add your own variants, check out Themed components—Extend variants. Note that you lose the global variants when you add custom variants. :::

Sizes

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

{{"demo": "RadioSizes.js"}}

:::info To learn how to add custom sizes to the component, check out Themed components—Extend sizes. :::

Colors

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

{{"demo": "RadioColors.js"}}

Label

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

{{"demo": "RadioButtonLabel.js"}}

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

{{"demo": "RadioButtonControl.js"}}

Position

To swap the positions of a Radio and its label, use the CSS property flex-direction: row-reverse.

{{"demo": "RadioPositionEnd.js"}}

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.

{{"demo": "RadioButtonsGroup.js"}}

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:

{{"demo": "ControlledRadioButtonsGroup.js"}}

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

{{"demo": "RadioFocus.js"}}

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.

{{"demo": "OverlayRadio.js"}}

:::info Use the CSS variable --Radio-actionRadius to control the border radius of the clickable area. :::

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:

{{"demo": "IconsRadio.js"}}

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:

{{"demo": "IconlessRadio.js"}}

Common examples

Segmented controls

{{"demo": "ExampleSegmentedControls.js"}}

Tiers

This example demonstrates the composition of the components, and was inspired by this Dribbble shot from Tailwind Labs.

{{"demo": "ExampleTiers.js"}}

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.

{{"demo": "ExampleAlignmentButtons.js"}}

Payment methods

Mix Radio buttons with the List components to create a vertical or horizontal payment method list.

{{"demo": "ExamplePaymentChannels.js"}}

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.

{{"demo": "ExampleProductAttributes.js"}}

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>