复选框

当用户在一系列选项中遇到多个选择时，复选框为用户提供二元选择。

简介

复选框为用户提供二元选择（是或否，开或关）的图形化表示。它们最常以系列形式呈现，让用户可以做出多个选择。

Joy UI Checkbox 组件取代了原生的 HTML <input type="checkbox"> 元素，并为样式和可访问性提供了扩展选项。

基础

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

基本 Checkbox 组件是设置为未选中状态的单个输入框。使用 label 属性提供文本，并在输入框应默认选中时添加 defaultChecked。

LabelLabel

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

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

按 Enter 开始编辑

自定义

变体

Checkbox 组件支持 Joy UI 的四种全局变体：solid、soft、outlined 和 plain。默认情况下，当未选中时，Checkbox 设置为 outlined；当选中时，变体更改为 solid。

将 variant 属性添加到您的 Checkbox 会覆盖此默认行为。尝试选中和取消选中以下演示中的复选框，以查看差异

SolidSoftOutlinedPlain

<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 开始编辑

尺寸

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

SmallMediumLarge

<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 开始编辑

图标

默认情况下，Checkbox 组件在未选中时为空。使用 uncheckedIcon 属性为未选中状态添加自定义图标。您也可以使用 checkedIcon 来自定义选中状态。

当我未选中时，我有一个图标

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

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

按 Enter 开始编辑

悬停时出现

您可以使用 uncheckedIcon 作为选中状态的“预览”，使其在用户悬停在空 Checkbox 上时出现。

下面的演示展示了如何通过使用 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 属性完全删除图标。在这种情况下，Checkbox 的状态通过应用于标签的变体类型来传达。尝试单击以下演示中的 Checkbox 标签，以查看其工作原理

焦点轮廓

默认情况下，焦点轮廓包裹 Checkbox 输入框及其标签。要设置焦点轮廓，使其仅包裹输入框，请定位 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 属性将焦点轮廓从 Checkbox 移动到其容器，使整个容器可点击以切换 Checkbox 的状态。这适用于任何具有定位的包装器元素——下面的演示使用 Sheet（默认情况下，它具有 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 开始编辑

不确定状态

默认的 Checkbox 是双态的：用户可以在选中和未选中之间切换。

还有一种三态或不确定状态的 Checkbox 选项，它支持一种称为“部分选中”的状态。

这种不确定状态通常用于传达一组 Checkbox 中只有部分被选中的事实。因此，它通常保留给可以控制其子项状态的父 Checkbox。

下面的演示展示了如何在父 Checkbox 上实现 indeterminate 属性，该属性监视其子项中的选中状态。如果只有一个子项被选中，则父项显示不确定状态。单击父 Checkbox 会切换选择和取消选择所有子项。

父项

子项 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';

使用 Form Control 和 Form Helper Text 组件为 Checkbox 添加描述。Checkbox 将通过 aria-describedby 属性链接到辅助文本。

标签

Checkbox 的描述。

<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 开始编辑

组

要对多个 Checkbox 进行分组，请将它们包装在带有 role="group" 的容器组件（如 Box）中。

与 List 组件结合使用，以确保一致的间距，并使屏幕阅读器能够将 Checkbox 组解释为列表。了解有关复选框的无障碍设计模式的更多信息，请参阅 W3C 文档。

三明治酱料

生菜
番茄
芥末

常见示例

要将交互元素与 Checkbox 一起使用，您可以将其与 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 开始编辑

过滤状态

此示例使用 List Item 和 Checkbox 组件可用的变体和颜色来传达状态更改。

过滤状态

付款被拒绝
8
交付错误
24
地址错误

过滤成员

此示例使用 CSS flexDirection: 'rowReverse' 属性来定位标签和图标。不要忘记使用 label 属性来确保正确的 Checkbox 可访问性。

团队成员

Friedrich Oberbrunner
Adeline O'Reilly
Fernando Pidrillio

选择型纸片

您可以使用 Checkbox 来重新创建一种 Chip 组件，该组件通常以一组过滤选项的形式实现。

视口清单

移动设备
笔记本电脑
显示器

解剖结构

Checkbox 组件由一个根 <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 Checkbox 完全拥有组件的设计，无需覆盖 Material UI 或 Joy UI 样式。此组件的无样式版本是重度自定义和更小捆绑包大小的理想选择。

API

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

<Checkbox />

复选框

Playground

悬停时出现

无图标