核取方塊

核取方塊允許使用者從一組項目中選擇一個或多個項目。

核取方塊可用於開啟或關閉選項。

如果列表中出現多個選項，您可以使用核取方塊而不是開啟/關閉開關來節省空間。如果只有單個選項，請避免使用核取方塊，而改用開啟/關閉開關。

基本核取方塊

<Checkbox {...label} defaultChecked />
<Checkbox {...label} />
<Checkbox {...label} disabled />
<Checkbox {...label} disabled checked />

<Checkbox {...label} defaultChecked />
<Checkbox {...label} />
<Checkbox {...label} disabled />
<Checkbox {...label} disabled checked />

按下 Enter 開始編輯

尺寸

使用 size 屬性或自訂 svg 圖示的字體大小來變更核取方塊的尺寸。

<Checkbox {...label} defaultChecked size="small" />
<Checkbox {...label} defaultChecked />
<Checkbox
  {...label}
  defaultChecked
  sx={{ '& .MuiSvgIcon-root': { fontSize: 28 } }}
/>

<Checkbox {...label} defaultChecked size="small" />
<Checkbox {...label} defaultChecked />
<Checkbox
  {...label}
  defaultChecked
  sx={{ '& .MuiSvgIcon-root': { fontSize: 28 } }}
/>

按下 Enter 開始編輯

顏色

<Checkbox {...label} defaultChecked />
<Checkbox {...label} defaultChecked color="secondary" />
<Checkbox {...label} defaultChecked color="success" />
<Checkbox {...label} defaultChecked color="default" />
<Checkbox
  {...label}
  defaultChecked
  sx={{
    color: pink[800],
    '&.Mui-checked': {
      color: pink[600],
    },
  }}
/>

<Checkbox {...label} defaultChecked />
<Checkbox {...label} defaultChecked color="secondary" />
<Checkbox {...label} defaultChecked color="success" />
<Checkbox {...label} defaultChecked color="default" />
<Checkbox
  {...label}
  defaultChecked
  sx={{
    color: pink[800],
    '&.Mui-checked': {
      color: pink[600],
    },
  }}
/>

按下 Enter 開始編輯

圖示

<Checkbox {...label} icon={<FavoriteBorder />} checkedIcon={<Favorite />} />
<Checkbox
  {...label}
  icon={<BookmarkBorderIcon />}
  checkedIcon={<BookmarkIcon />}
/>

<Checkbox {...label} icon={<FavoriteBorder />} checkedIcon={<Favorite />} />
<Checkbox
  {...label}
  icon={<BookmarkBorderIcon />}
  checkedIcon={<BookmarkIcon />}
/>

按下 Enter 開始編輯

受控

您可以使用 checked 和 onChange 屬性控制核取方塊

<Checkbox
  checked={checked}
  onChange={handleChange}
  inputProps={{ 'aria-label': 'controlled' }}
/>

<Checkbox
  checked={checked}
  onChange={handleChange}
  inputProps={{ 'aria-label': 'controlled' }}
/>

按下 Enter 開始編輯

不確定

在表單中，核取方塊輸入只能有兩種狀態：已核取或未核取。它要么提交其值，要么不提交。在視覺上，核取方塊可以有三種狀態：已核取、未核取或不確定。

您可以使用 indeterminateIcon 屬性變更不確定圖示。

父層

子層 1子層 2

<FormControlLabel
  label="Parent"
  control={
    <Checkbox
      checked={checked[0] && checked[1]}
      indeterminate={checked[0] !== checked[1]}
      onChange={handleChange1}
    />
  }
/>
{children}

<FormControlLabel
  label="Parent"
  control={
    <Checkbox
      checked={checked[0] && checked[1]}
      indeterminate={checked[0] !== checked[1]}
      onChange={handleChange1}
    />
  }
/>
{children}

按下 Enter 開始編輯

FormGroup

FormGroup 是一個有用的包裝器，用於將選擇控制元件分組。

標籤位置

您可以變更標籤的位置

標籤位置

下方尾端

客製化

以下是自訂元件的範例。您可以在覆寫文件頁面中了解更多資訊。

<BpCheckbox />
<BpCheckbox defaultChecked />
<BpCheckbox disabled />

<BpCheckbox />
<BpCheckbox defaultChecked />
<BpCheckbox disabled />

按下 Enter 開始編輯

🎨 如果您正在尋找靈感，可以查看 MUI Treasury 的客製化範例。

何時使用

可訪問性

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

所有表單控件都應該有標籤，這包括選項按鈕、核取方塊和開關。在大多數情況下，這是通過使用 <label> 元素 (FormControlLabel) 完成的。
當無法使用標籤時，需要直接向輸入元件添加屬性。在這種情況下，您可以通過 inputProps 屬性應用額外的屬性（例如 aria-label、aria-labelledby、title）。

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

API

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