Checkbox 选择框

在一个集合内，用户可以通过多选框组件进行一项或者多项选择。

多选框可用于打开或关闭选项。

若一个列表存在多个选择项时，使用多选框替代开关控件，可以节省空间。若只存在一个选择项，请避免使用多选框，而改用开关控件。

简单的多选框

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

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

Press Enter to start editing

Size 大小

使用 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 } }}
/>

Press Enter to start editing

Color 颜色

<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],
    },
  }}
/>

Press Enter to start editing

图标

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

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

Press Enter to start editing

Controlled

您可以使用 checked 和 onChange 属性控制复选框：

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

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

Press Enter to start editing

不确定的状态

多选框在表单中只能存在两种状态：已选中或未选中。在其状态下提交的值只有存在和空两种形式。 Visually, there are three states a checkbox can be in: checked, unchecked, or indeterminate.

Parent

Child 1Child 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}

Press Enter to start editing

表单组

FormGroup 是一个用于对选择控件进行分组的有益的容器

标签放置

You can change the placement of the label:

Label placement

TopStartBottomEnd

自定义的多选框

Here is an example of customizing the component. You can learn more about this in the overrides documentation page.

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

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

Press Enter to start editing

🎨 If you are looking for inspiration, you can check MUI Treasury's customization examples.

什么时候使用

无障碍设计

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

所有表单控件都应该带有标签，而这包括了单选按钮，复选框和开关。 In most cases, this is done by using the <label> element (FormControlLabel).
如果无法使用标签，您则必须在输入组件中直接添加属性。在这种情况下，您可以通过 inputProps 属性来应用附加的属性（例如 aria-label, aria-labelledby, title）。

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

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.