核取方塊

當一系列選項呈現給使用者時，核取方塊讓使用者可以做出二元選擇。

簡介

核取方塊為使用者提供二元選擇（是或否、開啟或關閉）的圖形化表示。它們最常見於一系列選項中，讓使用者可以做出多個選擇。

Joy UI 核取方塊元件取代了原生 HTML <input type="checkbox"> 元素，並為樣式和可訪問性提供了擴展選項。

基本用法

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

基本的核取方塊元件是一個設定為未核取狀態的單一輸入框。使用 label 屬性提供文字，並在預設情況下應核取輸入框時新增 defaultChecked。

標籤標籤

<Checkbox label="Label" />
<Checkbox label="Label" defaultChecked />

<Checkbox label="Label" />
<Checkbox label="Label" defaultChecked />

按下 Enter 開始編輯

客製化

變體

核取方塊元件支援 Joy UI 的四種全域變體：solid、soft、outlined 和 plain。預設情況下，當未核取時，核取方塊設定為 outlined；當核取時，變體變更為 solid。

將 variant 屬性新增至您的核取方塊會覆寫此預設行為。嘗試在下面的演示中核取和取消核取核取方塊，以查看差異

實心柔和外框樸素

<Checkbox label="Solid" variant="solid" defaultChecked />
<Checkbox label="Soft" variant="soft" defaultChecked />
<Checkbox label="Outlined" variant="outlined" defaultChecked />
<Checkbox label="Plain" variant="plain" defaultChecked />

<Checkbox label="Solid" variant="solid" defaultChecked />
<Checkbox label="Soft" variant="soft" defaultChecked />
<Checkbox label="Outlined" variant="outlined" defaultChecked />
<Checkbox label="Plain" variant="plain" defaultChecked />

按下 Enter 開始編輯

尺寸

核取方塊元件有三種尺寸：sm、md（預設）和 lg。

小中大

<Checkbox label="Small" size="sm" defaultChecked />
<Checkbox label="Medium" size="md" defaultChecked />
<Checkbox label="Large" size="lg" defaultChecked />

<Checkbox label="Small" size="sm" defaultChecked />
<Checkbox label="Medium" size="md" defaultChecked />
<Checkbox label="Large" size="lg" defaultChecked />

按下 Enter 開始編輯

顏色

主題中包含的每個調色盤都可透過 color 屬性使用。

<Checkbox label="Primary" color="primary" defaultChecked />
<Checkbox label="Neutral" color="neutral" defaultChecked />
<Checkbox label="Danger" color="danger" defaultChecked />
<Checkbox label="Success" color="success" defaultChecked />
<Checkbox label="Warning" color="warning" defaultChecked />

<Checkbox label="Primary" color="primary" defaultChecked />
<Checkbox label="Neutral" color="neutral" defaultChecked />
<Checkbox label="Danger" color="danger" defaultChecked />
<Checkbox label="Success" color="success" defaultChecked />
<Checkbox label="Warning" color="warning" defaultChecked />

按下 Enter 開始編輯

圖示

預設情況下，核取方塊元件在未核取時為空。使用 uncheckedIcon 屬性為未核取狀態新增自訂圖示。您也可以使用 checkedIcon 來自訂核取狀態。

當未核取時，我有圖示

<Checkbox uncheckedIcon={<Close />} label="I have an icon when unchecked" />

<Checkbox uncheckedIcon={<Close />} label="I have an icon when unchecked" />

按下 Enter 開始編輯

在懸停時顯示

您可以將 uncheckedIcon 作為核取狀態的「預覽」，使其在使用者將滑鼠懸停在空白核取方塊上方時顯示。

下面的演示示範如何使用 svg 選擇器定位圖示，並套用 opacity 以獲得平滑效果

我的未核取圖示在懸停時顯示

<Checkbox
  uncheckedIcon={<Done />}
  label="My unchecked icon appears on hover"
  slotProps={{
    root: ({ checked, focusVisible }) => ({
      sx: !checked
        ? {
            '& svg': { opacity: focusVisible ? 1 : 0 },
            '&:hover svg': {
              opacity: 1,
            },
          }
        : undefined,
    }),
  }}
/>

<Checkbox
  uncheckedIcon={<Done />}
  label="My unchecked icon appears on hover"
  slotProps={{
    root: ({ checked, focusVisible }) => ({
      sx: !checked
        ? {
            '& svg': { opacity: focusVisible ? 1 : 0 },
            '&:hover svg': {
              opacity: 1,
            },
          }
        : undefined,
    }),
  }}
/>

按下 Enter 開始編輯

沒有圖示

使用 disableIcon 屬性完全移除圖示。在這種情況下，核取方塊的狀態是透過套用至標籤的變體類型來傳達的。嘗試點擊下面的演示中的核取方塊標籤，以查看其運作方式

焦點外框

預設情況下，焦點外框會包圍核取方塊輸入框及其標籤。若要設定焦點外框使其僅包圍輸入框，請定位 checkboxClasses.checkbox 類別並新增 position: 'relative'，如下面的演示所示

完整包圍輸入框包圍

<Checkbox
  label="Fully wrapped"
  defaultChecked
  // to demonstrate the focus outline
  slotProps={{ action: { className: checkboxClasses.focusVisible } }}
/>
<Checkbox
  label="Input wrapped"
  defaultChecked
  sx={{ [`& > .${checkboxClasses.checkbox}`]: { position: 'relative' } }}
  // to demonstrate the focus outline
  slotProps={{ action: { className: checkboxClasses.focusVisible } }}
/>

<Checkbox
  label="Fully wrapped"
  defaultChecked
  // to demonstrate the focus outline
  slotProps={{ action: { className: checkboxClasses.focusVisible } }}
/>
<Checkbox
  label="Input wrapped"
  defaultChecked
  sx={{ [`& > .${checkboxClasses.checkbox}`]: { position: 'relative' } }}
  // to demonstrate the focus outline
  slotProps={{ action: { className: checkboxClasses.focusVisible } }}
/>

按下 Enter 開始編輯

可點擊容器

使用 overlay 屬性將焦點外框從核取方塊移至其容器，使整個容器可點擊以切換核取方塊的狀態。這適用於任何具有定位的包裝元素——下面的演示使用工作表（預設情況下，它具有 relative 定位）

焦點在我身上

我的父元素接收焦點

<Sheet variant="outlined">
  <Checkbox overlay label="Focus on me" />
</Sheet>
<Sheet variant="outlined">
  <Checkbox
    label="My parent receives focus"
    overlay
    // Force the outline to appear in the demo. Usually, you don't need this in your project.
    slotProps={{ action: { className: checkboxClasses.focusVisible } }}
  />
</Sheet>

<Sheet variant="outlined">
  <Checkbox overlay label="Focus on me" />
</Sheet>
<Sheet variant="outlined">
  <Checkbox
    label="My parent receives focus"
    overlay
    // Force the outline to appear in the demo. Usually, you don't need this in your project.
    slotProps={{ action: { className: checkboxClasses.focusVisible } }}
  />
</Sheet>

按下 Enter 開始編輯

不確定狀態

預設的核取方塊是雙狀態：使用者可以在核取和未核取之間切換。

還有三狀態或不確定狀態核取方塊的選項，它支援稱為「部分核取」的狀態。

這種不確定狀態通常用於傳達一組核取方塊中只有部分被核取的事實。因此，它通常保留給可以控制其子元素狀態的父核取方塊。

下面的演示示範如何在監看其子元素中核取狀態的父核取方塊上實作 indeterminate 屬性。如果只有一個子元素被核取，則父元素會顯示不確定狀態。點擊父核取方塊會切換選取和取消選取所有子元素。

父元素

子元素 1子元素 2

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

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

按下 Enter 開始編輯

輔助文字

import FormControl from '@mui/joy/FormControl';
import FormHelperText from '@mui/joy/FormHelperText';

使用表單控制和表單輔助文字元件為核取方塊新增描述。核取方塊將透過 aria-describedby 屬性連結到輔助文字。

標籤

核取方塊的描述。

<FormControl>
  <Checkbox label="Label" />
  <FormHelperText>A description for the Checkbox.</FormHelperText>
</FormControl>

<FormControl>
  <Checkbox label="Label" />
  <FormHelperText>A description for the Checkbox.</FormHelperText>
</FormControl>

按下 Enter 開始編輯

群組

若要將多個核取方塊分組，請將它們包裝在具有 role="group" 的容器元件（如 Box）中。

與清單元件結合使用，以確保一致的間距，並使螢幕閱讀器能夠將核取方塊群組解讀為清單。在 W3C 文件中了解更多關於核取方塊的無障礙設計模式。

三明治醬料

萵苣
番茄
芥末

常見範例

若要將互動式元素與核取方塊一起使用，您可以將其與 FormControl 和 FormHelperText 包裝在一起。

我已閱讀並同意條款與細則.

閱讀我們的條款與細則。

<FormControl size="sm" sx={{ width: 400 }}>
  <Checkbox
    label={
      <React.Fragment>
        I have read and agree to the{' '}
        <Typography sx={{ fontWeight: 'md' }}>terms and conditions</Typography>.
      </React.Fragment>
    }
  />
  <FormHelperText>
    <Typography level="body-sm">
      Read our <Link href="#link">terms and conditions</Link>.
    </Typography>
  </FormHelperText>
</FormControl>

<FormControl size="sm" sx={{ width: 400 }}>
  <Checkbox
    label={
      <React.Fragment>
        I have read and agree to the{' '}
        <Typography sx={{ fontWeight: 'md' }}>terms and conditions</Typography>.
      </React.Fragment>
    }
  />
  <FormHelperText>
    <Typography level="body-sm">
      Read our <Link href="#link">terms and conditions</Link>.
    </Typography>
  </FormHelperText>
</FormControl>

按下 Enter 開始編輯

篩選狀態

此範例使用清單項目和核取方塊元件可用的變體和顏色來傳達狀態變更。

篩選狀態

付款遭拒
8
交付錯誤
24
地址錯誤

篩選成員

此範例使用 CSS flexDirection: 'rowReverse' 屬性來定位標籤和圖示。別忘了使用 label 屬性以確保正確的核取方塊可訪問性。

團隊成員

Friedrich Oberbrunner
Adeline O'Reilly
Fernando Pidrillio

選擇晶片

您可以使用核取方塊重新建立一種晶片元件，該元件通常以一組篩選選項的形式實作。

視窗檢查清單

行動裝置
筆記型電腦
螢幕

剖析

核取方塊元件由根 <span> 組成，它包裝了輸入框和 <label>（如果存在）。請注意，實際的 <input type="checkbox"> 雙重巢狀於代表 checkbox 和 action 插槽的 <span> 元素中。

<span class="MuiCheckbox-root">
  <span class="MuiCheckbox-checkbox">
    <span class="MuiCheckbox-action">
      <input type="checkbox" class="MuiCheckbox-input" value />
    </span>
  </span>
  <label class="MuiCheckbox-label">
    <!-- label text -->
  </label>
</span>

無樣式

使用 Base UI 核取方塊完全掌握元件的設計，而無需覆寫 Material UI 或 Joy UI 樣式。此元件的無樣式版本是高度客製化的理想選擇，且套件大小更小。

API

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

<Checkbox />

核取方塊

遊樂場

在懸停時顯示

沒有圖示