Radio

單選按鈕讓使用者從一組選項中選擇一個選項。

簡介

單選按鈕讓使用者做出互斥的選擇（例如：「這個」或「那個」）。從可用的選項集中，只允許選擇一個。

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

基本用法

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。

變體

外框柔和實心樸素

<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（如果存在），這會將該屬性傳遞給其中巢狀的每個單獨的 Radio 按鈕。

成員

個人1

個人2

個人3

自訂圖示

使用 checkedIcon 和 uncheckedIcon 屬性為單選按鈕新增自訂圖示，分別對應於每個狀態。以下示範顯示如何將自訂 checkedIcon 應用於位於每個工作表角落的單選按鈕

網站

文件

社群帳號

無圖示

使用 disableIcon 屬性移除單選按鈕的圖示。在這種情況下，您需要使用諸如邊框和背景顏色之類的 CSS 屬性來傳達單選按鈕的狀態，如下面的示範所示

儲存空間

512GB SSD 儲存空間

1TB SSD 儲存空間

2TB SSD 儲存空間

常見範例

分段控制

對齊

flex-startcenterflex-end

層級

此範例示範了元件的組合，其靈感來自Tailwind Labs 的這張 Dribbble 截圖。

小型

適用於輕量級背景作業，例如傳送電子郵件

中型

適用於圖像調整大小、匯出 PDF 等任務。

大型

適用於密集型任務，例如影片編碼等。

對齊按鈕

此範例使用圖示作為一組單選按鈕的標籤，以重新建立切換按鈕的表單和功能。在這種情況下，您必須為依賴螢幕閱讀器的使用者提供輸入插槽的 aria-label。

付款方式

將單選按鈕與清單元件混合使用，以建立垂直或水平付款方式清單。

使用以下方式付款

信用卡

Paypal

QR Code

電子商務產品屬性

此範例示範了使用 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 Authoring Practices 以取得更多詳細資訊。

結構

Radio Group 元件由一個根 <div> 元素組成，該元素可以包裝多個 Radio 元件。

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

Radio 元件由一個根 <span> 組成，其中還有巢狀的 <span> 元素，用於單選按鈕、圖示、動作（帶有巢狀 <input>）及其關聯的 <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>

無樣式

使用 Base UI Radio 完全擁有元件的設計，沒有 Material UI 或 Joy UI 樣式需要覆寫。此元件的無樣式版本是需要大量自訂且捆綁包尺寸較小的理想選擇。

API

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

Radio

Playground