<input type="checkbox">

Baseline 已广泛支持

此特性已相当成熟，可在许多设备和浏览器版本上使用。自 ⁨2015 年 7 月⁩以来，各浏览器均已提供此特性。

<input> 元素，其类型为 checkbox，默认情况下呈现为复选框，当被激活时（例如在官方政府纸质表格中），复选框会被选中（打勾）。具体外观取决于浏览器运行的操作系统配置。通常是一个正方形，但可能有圆角。复选框允许你选择单个值以在表单中提交（或不提交）。

试一试

<fieldset>
  <legend>Choose your monster's features:</legend>

  <div>
    <input type="checkbox" id="scales" name="scales" checked />
    <label for="scales">Scales</label>
  </div>

  <div>
    <input type="checkbox" id="horns" name="horns" />
    <label for="horns">Horns</label>
  </div>
</fieldset>

p,
label {
  font:
    1rem "Fira Sans",
    sans-serif;
}

input {
  margin: 0.4rem;
}

注意： 单选按钮与复选框相似，但有一个重要区别 —— 同名的单选按钮被分组到一个集合中，一次只能选择一个单选按钮，而复选框允许你单独打开或关闭单个值。当存在多个同名控件时，单选按钮允许从所有控件中选择一个，而复选框允许选择多个值。

值

表示复选框值的字符串。这不会显示在客户端，但在服务器端，这是随复选框的 name 提交的数据的 value。请看以下示例：

html

<form>
  <div>
    <input
      type="checkbox"
      id="subscribeNews"
      name="subscribe"
      value="newsletter" />
    <label for="subscribeNews">Subscribe to newsletter?</label>
  </div>
  <div>
    <button type="submit">Subscribe</button>
  </div>
</form>

在此示例中，我们有一个 name 为 subscribe，一个 value 为 newsletter。当表单提交时，数据名/值对将是 subscribe=newsletter。

如果省略 value 属性，则复选框的默认值为 on，因此在这种情况下提交的数据将是 subscribe=on。

注意：如果复选框在提交表单时未被选中，则其名称和值都不会提交到服务器。没有仅限 HTML 的方法来表示复选框的未选中状态（例如 value=unchecked）。如果你想在复选框未选中时提交其默认值，你可以使用 JavaScript 在表单中创建一个 <input type="hidden">，其值表示未选中状态。

附加属性

除了所有 <input> 元素共享的通用属性之外，checkbox 输入支持以下属性。

checked: 一个布尔属性，指示此复选框在默认情况下（页面加载时）是否被选中。它不表示此复选框当前是否被选中：如果复选框的状态发生改变，此内容属性不反映该改变。（只有 HTMLInputElement 的 checked IDL 属性会被更新。）

注意：与其他输入控件不同，复选框的值仅在复选框当前为 checked 时才包含在提交的数据中。如果是，则复选框 value 属性的值作为输入的报告值，如果未设置 value，则为 on。与其他浏览器不同，Firefox 默认情况下在页面加载时保留 <input> 的动态选中状态。使用 autocomplete 属性来控制此功能。
value: value 属性是所有 <input> 共享的属性；然而，它对于 checkbox 类型的输入有特殊用途：当表单提交时，只有当前被选中的复选框才会提交到服务器，报告的值是 value 属性的值。如果未另行指定 value，则默认为字符串 on。这在上面的值部分中已演示。

使用复选框输入

我们已经在上面涵盖了复选框最基本的使用。现在让我们看看你将需要的其他常见的与复选框相关的功能和技术。

处理多个复选框

我们上面看到的例子只包含一个复选框；在实际情况中，你可能会遇到多个复选框。如果它们完全不相关，那么你可以像上面所示那样单独处理它们。然而，如果它们都相关，事情就不那么简单了。

例如，在下面的演示中，我们包含多个复选框，允许用户选择他们的兴趣（参见示例部分中的完整版本）。

html

<fieldset>
  <legend>Choose your interests</legend>
  <div>
    <input type="checkbox" id="coding" name="interest" value="coding" />
    <label for="coding">Coding</label>
  </div>
  <div>
    <input type="checkbox" id="music" name="interest" value="music" />
    <label for="music">Music</label>
  </div>
</fieldset>

在此示例中，你将看到我们为每个复选框指定了相同的 name。如果两个复选框都被选中然后提交表单，你将收到一个像这样的名称/值对字符串：interest=coding&interest=music。当此字符串到达服务器时，你需要将其解析为非关联数组，这样 interest 的所有值（而不仅仅是最后一个值）都被捕获。对于 Python 中使用的一种技术，请参阅使用单个服务器端变量处理多个复选框。

默认选中复选框

要使复选框默认选中，请为其指定 checked 属性。请参阅以下示例：

html

<fieldset>
  <legend>Choose your interests</legend>
  <div>
    <input type="checkbox" id="coding" name="interest" value="coding" checked />
    <label for="coding">Coding</label>
  </div>
  <div>
    <input type="checkbox" id="music" name="interest" value="music" />
    <label for="music">Music</label>
  </div>
</fieldset>

为复选框提供更大的点击区域

在上述示例中，您可能已经注意到，您可以通过单击其关联的 <label> 元素以及复选框本身来切换复选框。这是 HTML 表单标签一个非常有用的功能，它使得点击您想要的选项更加容易，尤其是在智能手机等小屏幕设备上。

除了可访问性之外，这也是在表单上正确设置 <label> 元素的另一个好理由。

不确定状态的复选框

复选框可以处于不确定状态。这通过 JavaScript 使用 HTMLInputElement 对象的 indeterminate 属性来设置（不能通过 HTML 属性设置）

inputInstance.indeterminate = true;

当 indeterminate 为 true 时，在大多数浏览器中，复选框会在框中显示一条水平线（它看起来有点像连字符或减号），而不是勾选/打勾。

注意：这纯粹是视觉上的改变。它对复选框的 value 是否用于表单提交没有影响。这取决于 checked 状态，而与 indeterminate 状态无关。

此属性的用例不多。最常见的情况是当有一个复选框“拥有”一些子选项（这些子选项也是复选框）时。如果所有子选项都被选中，则拥有复选框也被选中；如果它们都未选中，则拥有复选框也未选中。如果任何一个或多个子选项的状态与其他选项不同，则拥有复选框处于不确定状态。

这可以在下面的示例中看到（感谢 CSS Tricks 的启发）。在此示例中，我们跟踪为食谱收集的食材。当你选中或取消选中食材的复选框时，一个 JavaScript 函数会检查已选中食材的总数

如果都没有选中，则食谱名称的复选框设置为未选中。
如果选中了一个或两个，则食谱名称的复选框设置为 indeterminate。
如果所有三个都选中，则食谱名称的复选框设置为 checked。

因此，在这种情况下，indeterminate 状态用于表示食材收集已经开始，但食谱尚未完成。

const overall = document.querySelector("#enchantment");
const ingredients = document.querySelectorAll("ul input");

overall.addEventListener("click", (e) => {
  e.preventDefault();
});

for (const ingredient of ingredients) {
  ingredient.addEventListener("click", updateDisplay);
}

function updateDisplay() {
  let checkedCount = 0;
  for (const ingredient of ingredients) {
    if (ingredient.checked) {
      checkedCount++;
    }
  }

  if (checkedCount === 0) {
    overall.checked = false;
    overall.indeterminate = false;
  } else if (checkedCount === ingredients.length) {
    overall.checked = true;
    overall.indeterminate = false;
  } else {
    overall.checked = false;
    overall.indeterminate = true;
  }
}

<form>
  <fieldset>
    <legend>Choose your interests</legend>
    <div>
      <label>
        <input type="checkbox" id="coding" name="interest" value="coding" />
        Coding
      </label>
    </div>
    <div>
      <label>
        <input type="checkbox" id="music" name="interest" value="music" />
        Music
      </label>
    </div>
    <div>
      <label>
        <input type="checkbox" id="art" name="interest" value="art" />
        Art
      </label>
    </div>
    <div>
      <label>
        <input type="checkbox" id="sports" name="interest" value="sports" />
        Sports
      </label>
    </div>
    <div>
      <label>
        <input type="checkbox" id="cooking" name="interest" value="cooking" />
        Cooking
      </label>
    </div>
    <div>
      <label>
        <input type="checkbox" id="other" name="interest" value="other" />
        Other
      </label>
      <input
        type="text"
        id="otherValue"
        name="other"
        aria-label="Other interest" />
    </div>
    <div>
      <button type="submit">Submit form</button>
    </div>
  </fieldset>
</form>

CSS

css

html {
  font-family: sans-serif;
}

form {
  width: 600px;
  margin: 0 auto;
}

div {
  margin-bottom: 10px;
}

fieldset {
  background: cyan;
  border: 5px solid blue;
}

legend {
  padding: 10px;
  background: blue;
  color: cyan;
}

JavaScript

const otherCheckbox = document.querySelector("#other");
const otherText = document.querySelector("#otherValue");
otherText.style.visibility = "hidden";

otherCheckbox.addEventListener("change", () => {
  if (otherCheckbox.checked) {
    otherText.style.visibility = "visible";
    otherText.value = "";
  } else {
    otherText.style.visibility = "hidden";
  }
});

技术摘要

值	表示复选框值的字符串。
事件	`change` 和 `input`
支持的常见属性	`checked`
IDL 属性	`checked`, `indeterminate` 和 `value`
DOM 接口	`HTMLInputElement`
方法	`select()`
隐式 ARIA 角色	`checkbox`

规范

规范
HTML # 复选框状态（类型=复选框）

浏览器兼容性

另见

:checked, :indeterminate: CSS 选择器，可根据复选框的当前状态对其进行样式设置
HTMLInputElement: 实现 <input> 元素的 HTML DOM API

帮助改进 MDN

了解如何贡献

此页面由MDN 贡献者最后修改于 2025 年 7 月 9 日。

在 GitHub 上查看此页面 • 报告此内容的问题