Checkbox 多选框

在一组备选项中进行多选。

WARNING

label 作为 value 来使用已经被废弃, 建议label 只用来表示展示的文字，这个被废弃的用法将会在 3.0.0 版本被移除，请考虑使用新 API 替换.

TIP

新的 API value 已在 2.6.0 版本添加，文档中的示例都将使用 value。如果您使用的版本低于 2.6.0 并且使用 checkbox-group，请参考：

基础用法

单独使用可以表示两种状态之间的切换，写在标签中的内容为 checkbox 按钮后的介绍。

checkbox-group元素能把多个 checkbox 管理为一组，只需要在 Group 中使用 v-model 绑定 Array 类型的变量即可。只有一个选项时的默认值类型为 Boolean，当选中时值为true。 el-checkbox 标签中的内容将成为复选框按钮之后的描述。

export function CheckboxBasic() {
  const [checked1, setChecked1] = useState(true);
  const [checked2, setChecked2] = useState(false);
  const [checked3, setChecked3] = useState(false);
  const [checked4, setChecked4] = useState(false);
  const [checked5, setChecked5] = useState(false);
  const [checked6, setChecked6] = useState(false);

  return (
    <>
      <div>
        <ElCheckbox checked={checked1} onCheckedChange={setChecked1} label="Option 1" size="large" />
        <ElCheckbox checked={checked2} onCheckedChange={setChecked2} label="Option 2" size="large" />
      </div>
      <div style={{ margin: "8px 0" }}>
        <ElCheckbox checked={checked3} onCheckedChange={setChecked3} label="Option 1" />
        <ElCheckbox checked={checked4} onCheckedChange={setChecked4} label="Option 2" />
      </div>
      <div style={{ marginTop: 8 }}>
        <ElCheckbox checked={checked5} onCheckedChange={setChecked5} label="Option 1" size="small" />
        <ElCheckbox checked={checked6} onCheckedChange={setChecked6} label="Option 2" size="small" />
      </div>
    </>
  );
}

禁用状态

多选框不可用状态。

设置 disabled 属性即可。

DisabledNot disabled

多选框组

适用于多个勾选框绑定到同一个数组的情景，通过是否勾选来表示这一组选项中选中的项。

在 el-checkbox 元素中定义 v-model 绑定变量，单一的 checkbox 中，默认绑定变量的值会是 Boolean，选中为 true。在 el-checkbox 组件中，value 是选择框的值。如果该组件下没有被传入内容，那么 label 将会作为 checkbox 按钮后的介绍。 value 也与数组中的元素值相对应。如果指定的值存在于数组中，就处于选择状态，反之亦然。

export function CheckboxGroupDemo() {
  const [checked, setChecked] = useState<CheckboxValueType[]>([
    "Value selected and disabled",
    "Value A",
  ]);
  return (
    <ElCheckboxGroup value={checked} onChange={setChecked}>
      <ElCheckbox label="Option A" value="Value A" />
      <ElCheckbox label="Option B" value="Value B" />
      <ElCheckbox label="Option C" value="Value C" />
      <ElCheckbox label="disabled" value="Value disabled" disabled />
      <ElCheckbox
        label="selected and disabled"
        value="Value selected and disabled"
        disabled
      />
    </ElCheckboxGroup>
  );
}

Options 属性 2.11.2

基础用法 el-checkbox-group 的快捷示例。您可以通过 props 属性自定义 options 的别名。

export function CheckboxOptions() {
  const [checked, setChecked] = useState<CheckboxValueType[]>([
    "Value selected and disabled",
    "Value A",
  ]);

  return (
    <ElCheckboxGroup
      value={checked}
      onChange={setChecked}
      options={OPTIONS}
      optionProps={OPTION_PROPS}
    />
  );
}

中间状态

indeterminate 属性用以表示 checkbox 的不确定状态，一般用于实现全选的效果

export function CheckboxIndeterminate() {
  const [checked, setChecked] = useState<CheckboxValueType[]>([
    "Shanghai",
    "Beijing",
  ]);
  const [checkAll, setCheckAll] = useState(false);
  const [indeterminate, setIndeterminate] = useState(true);

  return (
    <>
      <ElCheckbox
        checked={checkAll}
        indeterminate={indeterminate}
        onCheckedChange={(value) => {
          setCheckAll(value);
          setChecked(value ? [...ALL] : []);
          setIndeterminate(false);
        }}
      >
        Check all
      </ElCheckbox>
      <ElCheckboxGroup
        value={checked}
        onChange={(value) => {
          const count = value.length;
          setCheckAll(count === ALL.length);
          setIndeterminate(count > 0 && count < ALL.length);
          setChecked(value);
        }}
      >
        {ALL.map((city) => (
          <ElCheckbox key={city} value={city} label={city} />
        ))}
      </ElCheckboxGroup>
    </>
  );
}

可选项目数量的限制

使用 min 和 max 属性能够限制可以被勾选的项目的数量。

ShanghaiBeijingGuangzhouShenzhen

export function CheckboxMinMax() {
  const [checked, setChecked] = useState<CheckboxValueType[]>([
    "Shanghai",
    "Beijing",
  ]);
  return (
    <ElCheckboxGroup value={checked} onChange={setChecked} min={1} max={2}>
      {CITIES.map((city) => (
        <ElCheckbox key={city} value={city} label={city} />
      ))}
    </ElCheckboxGroup>
  );
}

按钮样式

按钮样式的多选组合。

只需要把 el-checkbox 元素替换为 el-checkbox-button 元素即可。此外，Element Plus 还提供了size属性。

export function CheckboxButton() {
  const [group1, setGroup1] = useState<CheckboxValueType[]>(["Shanghai"]);
  const [group2, setGroup2] = useState<CheckboxValueType[]>(["Shanghai"]);
  const [group3, setGroup3] = useState<CheckboxValueType[]>(["Shanghai"]);
  const [group4] = useState<CheckboxValueType[]>(["Shanghai"]);

  return (
    <>
      <div>
        <ElCheckboxGroup value={group1} onChange={setGroup1} size="large" type="button">
          {CITIES.map((city) => (
            <ElCheckbox key={city} value={city} label={city} />
          ))}
        </ElCheckboxGroup>
      </div>
      <div style={{ marginTop: 24 }}>
        <ElCheckboxGroup value={group2} onChange={setGroup2} type="button">
          {CITIES.map((city) => (
            <ElCheckbox key={city} value={city} label={city} />
          ))}
        </ElCheckboxGroup>
      </div>
      <div style={{ marginTop: 24 }}>
        <ElCheckboxGroup value={group3} onChange={setGroup3} size="small" type="button">
          {CITIES.map((city) => (
            <ElCheckbox
              key={city}
              value={city}
              label={city}
              disabled={city === "Beijing"}
            />
          ))}
        </ElCheckboxGroup>
      </div>
      <div style={{ marginTop: 24 }}>
        <ElCheckboxGroup value={group4} onChange={() => {}} size="small" disabled type="button">
          {CITIES.map((city) => (
            <ElCheckbox key={city} value={city} label={city} />
          ))}
        </ElCheckboxGroup>
      </div>
    </>
  );
}

带有边框

设置border属性可以渲染为带有边框的多选框。

export function CheckboxBorder() {
  const [checked1, setChecked1] = useState(true);
  const [checked2, setChecked2] = useState(false);
  const [checked3, setChecked3] = useState(false);
  const [checked4, setChecked4] = useState(true);
  const [group1, setGroup1] = useState<CheckboxValueType[]>(["Value1"]);

  return (
    <>
      <div>
        <ElCheckbox checked={checked1} onCheckedChange={setChecked1} label="Option1" size="large" border />
        <ElCheckbox checked={checked2} onCheckedChange={setChecked2} label="Option2" size="large" border />
      </div>
      <div style={{ marginTop: 16 }}>
        <ElCheckbox checked={checked3} onCheckedChange={setChecked3} label="Option1" border />
        <ElCheckbox checked={checked4} onCheckedChange={setChecked4} label="Option2" border />
      </div>
      <div style={{ marginTop: 16 }}>
        <ElCheckboxGroup value={group1} onChange={setGroup1} size="small">
          <ElCheckbox label="Option1" value="Value1" border />
          <ElCheckbox label="Option2" value="Value2" border />
        </ElCheckboxGroup>
      </div>
      <div style={{ marginTop: 16 }}>
        <ElCheckboxGroup value={group1} onChange={() => {}} size="small">
          <ElCheckbox label="Option1" value="Value1" border disabled />
          <ElCheckbox label="Option2" value="Value2" border disabled />
        </ElCheckboxGroup>
      </div>
    </>
  );
}

Checkbox API

Checkbox Attributes

属性名	说明	类型	默认值
checked	独立使用时是否选中	`boolean`	false
value	组内使用时标识本选项的值	`string` / `number` / `boolean`	—
label	显示文案，也可直接用 children	`string` / `ReactNode`	—
indeterminate	半选状态，仅控制样式	`boolean`	false
disabled	是否禁用	`boolean`	false
border	是否显示边框	`boolean`	false
size	尺寸	`enum`	—
button	button 形态，组内由 group 的 type 决定	`boolean`	—
name	原生 name 属性	`string`	—
id	原生 id 属性	`string`	—
tabIndex	原生 tabindex 属性	`number`	—

Checkbox Events

事件名	说明	参数
onCheckedChange	独立使用时选中态变化	`Function`

Checkbox Slots

插槽名	说明	React 写法
default	自定义选中项文案	`children` / `label`

CheckboxGroup Attributes

属性名	说明	类型	默认值
id	容器 id	`string`	—
aria-label	无障碍标签	`string`	checkbox-group
value	选中值集合	`array`	[]
disabled	是否禁用组内所有选项	`boolean`	false
min	最少选中数量	`number`	—
max	最多选中数量	`number`	—
size	尺寸	`enum`	—
fill	button 形态选中态的背景色	`string`	—
text-color	button 形态选中态的字体色	`string`	—
tag	容器标签名	`string`	div
type	渲染形态	`enum`	checkbox
options	数据化渲染选项	`array`	—
option-props	选项字段别名	`object`	—

CheckboxGroup Events

事件名	说明	参数
onChange	选中集合变化	`Function`

CheckboxGroup Slots

插槽名	说明	子标签
default	自定义选项内容；不传时按 options 渲染	Checkbox