W3cubDocs

/HTML

<input type="checkbox">

<input> elements of type checkbox are rendered by default as square boxes that are checked (ticked) when activated, like you might see in an official government paper form. They allow you to select single values for submission in a form (or not).

<input id="checkBox" type="checkbox">

Note: Radio buttons are similar to checkboxes, but with an important distinction — radio buttons are designed for selecting one value out of a few, whereas checkboxes allow you to turn single values on and off. A checkbox is basically a Boolean control — yes/no.

Value A DOMString representing the value of the checkbox.
Events change and input
Supported common attributes checked
IDL attributes checked and value
Methods select()

Value

A DOMString representing the value of the checkbox. This is never seen on the client-side, but on the server this is the value given to the data submitted with the checkbox's name. Take the following example:

<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>

In this example, we've got a name of "subscribe", and a value of "newsletter". When the form is submitted, the data name/value pair will be subscribe=newsletter. If the value attribute is omitted, the submitted data will be given a default value of on, so the submitted data in this case would be subscribe=on.

Note: If a checkbox is unchecked when its form is submitted, there is no value submitted to the server to represent its unchecked state (e.g. value=unchecked); the value is not submitted to the server at all.

Using checkbox inputs

We already covered the most basic use of checkboxes above. Let's now look at the other common checkbox-related features and techniques you'll need.

Handling multiple checkboxes

The example we saw above only contained one checkbox; in many real examples you'll be likely to encounter multiple checkboxes. If they are completely unrelated, then you can just deal with them all separate like we showed above. If however they are all related, things are not quite so simple.

For example, in the following demo we include multiple checkboxes to allow the user to select what interests they like (see the full version in the Examples section).

<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>

In this example you will see that we've given each checkbox the same name. If both checkboxes are checked and then the form is submitted, you'll get a string of name/value pairs submitted like this: interest=coding&interest=music. When this data reaches the server-side, you should be able to capture it as an array of related values and deal with it appropriately — see Handle Multiple Checkboxes with a Single Serverside Variable, for example.

Checking boxes by default

To make a checkbox checked by default, you simply give it the checked attribute. See the below example:

<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>

Indeterminate state checkboxes

There exists an indeterminate state of checkboxes, one in which it is not checked or unchecked, but undetermined. This is set using the HTMLInputElement object's indeterminate property via JavaScript (it cannot be set using an HTML attribute):

inputInstance.indeterminate = true;

A checkbox in indeterminate state has a horizontal line across it rather than a check/tick in most browsers.

There are not many use cases for this property, but the below example shows one (thanks to CSS Tricks for the inspiration). In this example we keep track of the ingredients we are collecting for a recipe. When you check or uncheck an ingredient's checkbox, a JavaScript function checks the total number of checked ingredients:

  • If none are checked, the recipe name's checkbox is set to unchecked.
  • If one or two are checked, the recipe name's checkbox is set to indeterminate.
  • If all three are checked, the recipe name's checkbox is set to checked.

So in this case the indeterminate state is used to state that collecting the ingredients has started, but the recipe is not yet complete.

Note: If you submit a form with an indeterminate checkbox, the same thing happens as if the form were unchecked — no data is submitted to represent the checkbox.

Validation

Buttons don't participate in constraint validation; they have no real value to be constrained.

Examples

The following example is an extended version of the "multiple checkboxes" example we saw above — it has more standard options, plus an "other" checkbox that when checked causes a text field to appear to enter the "other" option into. This is achieved via a simple block of JavaScript. The example also includes some CSS to improve the styling.

<form>
  <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>
    <div>
      <input type="checkbox" id="art" name="interest" value="art">
      <label for="art">Art</label>
    </div>
    <div>
      <input type="checkbox" id="sports" name="interest" value="sports">
      <label for="sports">Sports</label>
    </div>
    <div>
      <input type="checkbox" id="cooking" name="interest" value="cooking">
      <label for="cooking">Cooking</label>
    </div>
    <div>
      <input type="checkbox" id="other" name="interest" value="other">
      <label for="other">Other</label>
      <input type="text" id="otherValue" name="other">
    </div>
    <div>
      <button type="submit">Submit form</button>
    </div>
  </fieldset>
</form>
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;
}
var otherCheckbox = document.querySelector('input[value="other"]');
var otherText = document.querySelector('input[id="otherValue"]');
otherText.style.visibility = 'hidden';

otherCheckbox.onchange = function() {
  if(otherCheckbox.checked) {
    otherText.style.visibility = 'visible';
    otherText.value = '';
  } else {
    otherText.style.visibility = 'hidden';
  }
};

Specifications

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support (Yes) (Yes) (Yes) (Yes) (Yes)
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support (Yes) 4.0 (2.0) (Yes) (Yes) (Yes)

See also

© 2005–2017 Mozilla Developer Network and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox