单选

单选按钮允许用户从一组选项中选择一个选项。

简介

单选按钮允许用户做出互斥的选择（例如：“这个”或“那个”）。从可用选项集中仅允许选择一个。

单选按钮应默认选择最常用的选项。

基础知识

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

Joy UI 单选按钮的行为类似于原生 HTML <input type="radio">，因此它接受 checked、value 和 onChange 等属性。

<Radio
  checked={selectedValue === 'a'}
  onChange={handleChange}
  value="a"
  name="radio-buttons"
  slotProps={{ input: { 'aria-label': 'A' } }}
/>
<Radio
  checked={selectedValue === 'b'}
  onChange={handleChange}
  value="b"
  name="radio-buttons"
  slotProps={{ input: { 'aria-label': 'B' } }}
/>

<Radio
  checked={selectedValue === 'a'}
  onChange={handleChange}
  value="a"
  name="radio-buttons"
  slotProps={{ input: { 'aria-label': 'A' } }}
/>
<Radio
  checked={selectedValue === 'b'}
  onChange={handleChange}
  value="b"
  name="radio-buttons"
  slotProps={{ input: { 'aria-label': 'B' } }}
/>

按 Enter 开始编辑

自定义

变体

Radio 组件支持 Joy UI 的四种全局变体：outlined（默认）、soft、solid 和 plain。

变体

OutlinedSoftSolidPlain

<FormControl>
  <FormLabel>Variants</FormLabel>
  <RadioGroup defaultValue="outlined" name="radio-buttons-group">
    <Radio value="outlined" label="Outlined" variant="outlined" />
    <Radio value="soft" label="Soft" variant="soft" />
    <Radio value="solid" label="Solid" variant="solid" />
    <Radio value="plain" label="Plain" variant="plain" />
  </RadioGroup>
</FormControl>

<FormControl>
  <FormLabel>Variants</FormLabel>
  <RadioGroup defaultValue="outlined" name="radio-buttons-group">
    <Radio value="outlined" label="Outlined" variant="outlined" />
    <Radio value="soft" label="Soft" variant="soft" />
    <Radio value="solid" label="Solid" variant="solid" />
    <Radio value="plain" label="Plain" variant="plain" />
  </RadioGroup>
</FormControl>

按 Enter 开始编辑

尺寸

Radio 组件提供三种尺寸：sm、md（默认）和 lg

尺寸

小中大

<FormControl>
  <FormLabel>Sizes</FormLabel>
  <RadioGroup defaultValue="medium" name="radio-buttons-group">
    <Radio value="small" label="Small" size="sm" />
    <Radio value="medium" label="Medium" size="md" />
    <Radio value="large" label="Large" size="lg" />
  </RadioGroup>
</FormControl>

<FormControl>
  <FormLabel>Sizes</FormLabel>
  <RadioGroup defaultValue="medium" name="radio-buttons-group">
    <Radio value="small" label="Small" size="sm" />
    <Radio value="medium" label="Medium" size="md" />
    <Radio value="large" label="Large" size="lg" />
  </RadioGroup>
</FormControl>

按 Enter 开始编辑

颜色

主题中包含的每个调色板都可通过 color 属性使用。

<FormControl>
  <FormLabel>Colors</FormLabel>
  <RadioGroup defaultValue="medium" name="radio-buttons-group">
    <Radio value="primary" label="Primary" color="primary" />
    <Radio value="neutral" label="Neutral" color="neutral" />
    <Radio value="danger" label="Danger" color="danger" />
    <Radio value="success" label="Success" color="success" />
    <Radio value="warning" label="Warning" color="warning" />
  </RadioGroup>
</FormControl>

<FormControl>
  <FormLabel>Colors</FormLabel>
  <RadioGroup defaultValue="medium" name="radio-buttons-group">
    <Radio value="primary" label="Primary" color="primary" />
    <Radio value="neutral" label="Neutral" color="neutral" />
    <Radio value="danger" label="Danger" color="danger" />
    <Radio value="success" label="Success" color="success" />
    <Radio value="warning" label="Warning" color="warning" />
  </RadioGroup>
</FormControl>

按 Enter 开始编辑

位置

要交换单选按钮及其标签的位置，请使用 CSS 属性 flex-direction: row-reverse。

个人
团队
企业

与 Radio Group 一起使用

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

Radio Group 组件是多个 Radio 组件的理想包装器，因为它提供了用于分组和改进键盘导航可访问性的定制 API。

性别

女性

此单选按钮的辅助文本。

男性其他

这是辅助文本。

<FormControl>
  <FormLabel>Gender</FormLabel>
  <RadioGroup defaultValue="female" name="radio-buttons-group">
    <Radio
      value="female"
      label="Female"
      slotProps={{ input: { 'aria-describedby': 'female-helper-text' } }}
    />
    <FormHelperText id="female-helper-text">
      Helper text for this radio.
    </FormHelperText>
    <Radio value="male" label="Male" />
    <Radio value="other" label="Other" />
  </RadioGroup>
  <FormHelperText>This is helper text.</FormHelperText>
</FormControl>

<FormControl>
  <FormLabel>Gender</FormLabel>
  <RadioGroup defaultValue="female" name="radio-buttons-group">
    <Radio
      value="female"
      label="Female"
      slotProps={{ input: { 'aria-describedby': 'female-helper-text' } }}
    />
    <FormHelperText id="female-helper-text">
      Helper text for this radio.
    </FormHelperText>
    <Radio value="male" label="Male" />
    <Radio value="other" label="Other" />
  </RadioGroup>
  <FormHelperText>This is helper text.</FormHelperText>
</FormControl>

按 Enter 开始编辑

受控

使用 value 和 onChange 属性来控制单选按钮执行的操作。例如，下面演示中的单选按钮更新状态以反映所选选项

性别

女性男性其他

<FormControl>
  <FormLabel>Gender</FormLabel>
  <RadioGroup
    defaultValue="female"
    name="controlled-radio-buttons-group"
    value={value}
    onChange={handleChange}
    sx={{ my: 1 }}
  >
    <Radio value="female" label="Female" />
    <Radio value="male" label="Male" />
    <Radio value="other" label="Other" />
  </RadioGroup>
</FormControl>

<FormControl>
  <FormLabel>Gender</FormLabel>
  <RadioGroup
    defaultValue="female"
    name="controlled-radio-buttons-group"
    value={value}
    onChange={handleChange}
    sx={{ my: 1 }}
  >
    <Radio value="female" label="Female" />
    <Radio value="male" label="Male" />
    <Radio value="other" label="Other" />
  </RadioGroup>
</FormControl>

按 Enter 开始编辑

焦点轮廓

默认情况下，焦点轮廓会包裹单选按钮及其标签。如果您需要将焦点省略标签，请定位 radioClasses.radio 类并添加 position: 'relative'。

焦点

默认相对位置

选择一个选项并使用键盘 ↑↓ 查看焦点轮廓

<FormControl>
  <FormLabel>Focus</FormLabel>
  <RadioGroup name="radio-buttons-group-focus">
    <Radio value="default" label="Default" />
    <Radio
      value="relative"
      label="Position relative"
      sx={{ [`& .${radioClasses.radio}`]: { position: 'relative' } }}
    />
  </RadioGroup>
  <FormHelperText>
    Select an option and use keyboard ↑↓ to see the focus outline
  </FormHelperText>
</FormControl>

<FormControl>
  <FormLabel>Focus</FormLabel>
  <RadioGroup name="radio-buttons-group-focus">
    <Radio value="default" label="Default" />
    <Radio
      value="relative"
      label="Position relative"
      sx={{ [`& .${radioClasses.radio}`]: { position: 'relative' } }}
    />
  </RadioGroup>
  <FormHelperText>
    Select an option and use keyboard ↑↓ to see the focus outline
  </FormHelperText>
</FormControl>

按 Enter 开始编辑

叠加层

要使单选按钮的容器可点击，请使用 overlay 属性。

您也可以直接将此属性应用于 Radio Group（如果存在），这会将该属性传递给其中嵌套的每个单独的单选按钮。

成员

个人1

个人2

个人3

自定义图标

使用 checkedIcon 和 uncheckedIcon 属性为单选按钮添加自定义图标，分别对应于每种状态。下面的演示展示了如何将自定义 checkedIcon 应用于位于每个 Sheet 角落的单选按钮

网站

文档

社交帐户

无图标

使用 disableIcon 属性移除单选按钮的图标。在这种情况下，您需要使用 CSS 属性（如边框和背景颜色）来传达单选按钮的状态，如下面的演示所示

存储

512GB SSD 存储

1TB SSD 存储

2TB SSD 存储

常见示例

分段控件

对齐方式

flex-startcenterflex-end

层级

此示例演示了组件的组合，灵感来自Tailwind Labs 的这张 Dribbble 作品。

小型

适用于发送电子邮件等轻量级后台作业

中型

适用于图像大小调整、导出 PDF 等任务。

大型

适用于视频编码等密集型任务。

对齐按钮

此示例使用图标作为一组单选按钮的标签，以重现切换按钮的形式和功能。在这种情况下，您必须为依赖屏幕阅读器的用户在输入槽中提供 aria-label。

支付方式

将单选按钮与List 组件混合使用，以创建垂直或水平支付方式列表。

使用以下方式支付

信用卡

Paypal

二维码

电子商务产品属性

此示例演示了使用 Sheet 组件作为单选按钮容器的复杂自定义。焦点轮廓被自定义得更小，并且颜色会根据值而变化。

选中图标的颜色继承了单选按钮的 solid 变体，因此您无需手动选择与背景对比度足够的颜色。

可访问性

以下是一些确保您的单选按钮组件可访问的技巧

每个 Form Control 都应具有适当的标签。这包括单选按钮、复选框和开关。在大多数情况下，这是通过使用 Form Control 和 Form Label 元素来完成的。
当无法使用标签时，请确保直接在输入组件上添加属性，例如 aria-label、aria-labelledby 和/或 title。您也可以使用 slotProps.input 属性来添加它们。

<Radio
  value="radioA"
  slotProps={{
    input: {
      'aria-label': 'Radio A',
    },
  }}
/>

访问 WAI-ARIA 创作实践以了解更多详情。

解剖结构

Radio Group 组件由一个根 <div> 元素组成，该元素可以包裹多个 Radio 组件。

<div class="MuiRadioGroup-root">
  <!-- Radio components here -->
</div>

Radio 组件由一个根 <span> 组成，其中还嵌套了用于单选按钮、图标、操作（带有嵌套的 <input>）及其关联的 <label> 的 <span> 元素。

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

无样式

使用 Base UI Radio 完全拥有组件的设计，而无需覆盖 Material UI 或 Joy UI 样式。此无样式版本的组件是需要重度自定义且捆绑包尺寸更小的理想选择。

API

请参阅下面的文档，以获取此处提及的组件的所有可用属性和类的完整参考。

单选

Playground