單選按鈕群組

單選按鈕群組允許使用者從一組選項中選擇一個選項。

當使用者需要看到所有可用選項時，請使用單選按鈕。如果可用選項可以摺疊，請考慮使用Select 元件，因為它佔用的空間較小。

單選按鈕應預設選取最常用的選項。

單選按鈕群組

RadioGroup 是一個有用的包裝器，用於將 Radio 元件分組，它提供了更簡單的 API，以及群組適當的鍵盤可訪問性。

性別

女性男性其他

<FormControl>
  <FormLabel id="demo-radio-buttons-group-label">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-radio-buttons-group-label"
    defaultValue="female"
    name="radio-buttons-group"
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
    <FormControlLabel value="other" control={<Radio />} label="Other" />
  </RadioGroup>
</FormControl>

<FormControl>
  <FormLabel id="demo-radio-buttons-group-label">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-radio-buttons-group-label"
    defaultValue="female"
    name="radio-buttons-group"
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
    <FormControlLabel value="other" control={<Radio />} label="Other" />
  </RadioGroup>
</FormControl>

按下 Enter 鍵開始編輯

方向

若要水平排列按鈕，請設定 row 屬性

性別

女性男性其他其他

受控

您可以使用 value 和 onChange 屬性來控制單選按鈕

性別

女性男性

<FormControl>
  <FormLabel id="demo-controlled-radio-buttons-group">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-controlled-radio-buttons-group"
    name="controlled-radio-buttons-group"
    value={value}
    onChange={handleChange}
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
  </RadioGroup>
</FormControl>

<FormControl>
  <FormLabel id="demo-controlled-radio-buttons-group">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-controlled-radio-buttons-group"
    name="controlled-radio-buttons-group"
    value={value}
    onChange={handleChange}
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
  </RadioGroup>
</FormControl>

按下 Enter 鍵開始編輯

獨立單選按鈕

Radio 也可以獨立使用，無需 RadioGroup 包裝器。

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

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

按下 Enter 鍵開始編輯

尺寸

使用 size 屬性或自訂 svg 圖示的字體大小來變更單選按鈕的尺寸。

<Radio {...controlProps('a')} size="small" />
<Radio {...controlProps('b')} />
<Radio
  {...controlProps('c')}
  sx={{
    '& .MuiSvgIcon-root': {
      fontSize: 28,
    },
  }}
/>

<Radio {...controlProps('a')} size="small" />
<Radio {...controlProps('b')} />
<Radio
  {...controlProps('c')}
  sx={{
    '& .MuiSvgIcon-root': {
      fontSize: 28,
    },
  }}
/>

按下 Enter 鍵開始編輯

顏色

<Radio {...controlProps('a')} />
<Radio {...controlProps('b')} color="secondary" />
<Radio {...controlProps('c')} color="success" />
<Radio {...controlProps('d')} color="default" />
<Radio
  {...controlProps('e')}
  sx={{
    color: pink[800],
    '&.Mui-checked': {
      color: pink[600],
    },
  }}
/>

<Radio {...controlProps('a')} />
<Radio {...controlProps('b')} color="secondary" />
<Radio {...controlProps('c')} color="success" />
<Radio {...controlProps('d')} color="default" />
<Radio
  {...controlProps('e')}
  sx={{
    color: pink[800],
    '&.Mui-checked': {
      color: pink[600],
    },
  }}
/>

按下 Enter 鍵開始編輯

標籤位置

您可以使用 FormControlLabel 元件的 labelPlacement 屬性來變更標籤的位置

標籤位置

下方尾端

顯示錯誤

一般來說，單選按鈕應預設選取一個值。如果情況並非如此，則可以在提交表單時未選取任何值的情況下顯示錯誤

客製化

以下是客製化元件的範例。您可以在覆寫文件頁面中瞭解更多資訊。

性別

女性男性其他(已停用選項)

`useRadioGroup`

對於進階的客製化使用案例，公開了 useRadioGroup() Hook。它會傳回父單選按鈕群組的上下文值。Radio 元件在內部使用此 Hook。

API

import { useRadioGroup } from '@mui/material/RadioGroup';

傳回

value (物件)

value.name (字串 [選填])：用於參照控制項值的名稱。
value.onChange (函式 [選填])：在選取單選按鈕時觸發的回呼。
value.value (任何類型 [選填])：所選單選按鈕的值。

範例

第一個第二個

<RadioGroup name="use-radio-group" defaultValue="first">
  <MyFormControlLabel value="first" label="First" control={<Radio />} />
  <MyFormControlLabel value="second" label="Second" control={<Radio />} />
</RadioGroup>

<RadioGroup name="use-radio-group" defaultValue="first">
  <MyFormControlLabel value="first" label="First" control={<Radio />} />
  <MyFormControlLabel value="second" label="Second" control={<Radio />} />
</RadioGroup>

按下 Enter 鍵開始編輯

何時使用

核取方塊與單選按鈕

無障礙功能

(WAI-ARIA：https://www.w3.org/WAI/ARIA/apg/patterns/radio/)

所有表單控制項都應具有標籤，包括單選按鈕、核取方塊和開關。在大多數情況下，這是透過使用 <label> 元素 (FormControlLabel) 來完成的。
當無法使用標籤時，有必要將屬性直接新增至輸入元件。在這種情況下，您可以透過 inputProps 屬性套用其他屬性 (例如 aria-label、aria-labelledby、title)。

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

API

請參閱以下文件，以取得此處提及之元件的所有屬性和類別的完整參考。