Indeterminate checkboxes are weird
A checkbox usually has two states: checked and unchecked. But indeterminate checkboxes are in a third state: neither checked nor unchecked. The “checkedness” is not determined.
You have seen these before. The most common reason to have an indeterminate checkbox is when it is controlling a set of checkboxes. When none of the checkboxes are checked, neither is the master checkbox. When all of them are checked, so is the master checkbox. But if some are checked and some are not checked? The master checkbox state cannot be determined—it is indeterminate!
For example, each email in your GMail inbox has its own checkbox to select it. Up top, there is another checkbox. If you check that one, all of the emails are selected. Uncheck to deselect all emails.
If you only select a few emails, then the state of that checkbox cannot be determined. You have neither selected all of the emails, nor have you deselected all of them.
How do we make this happen?
Although indeterminate checkboxes are conceptually simple, implementing them correctly on a web page is not. We will be referencing the HTML specification about checkboxes and using that information to implement indeterminate checkboxes.
Content and IDL attributes
The first part of the specification we need to understand is this:
If the element’s indeterminate IDL attribute is set to true, then the control’s selection should be obscured as if the control was in a third, indeterminate, state.
This begs the question: What is an “IDL attribute”?
Glad you asked.
In HTML, elements have “content attributes”. These are the attributes
that you can set on HTML elements, such as
<p id="neat-paragraph" class="neato">Content attributes are neat</p>
HTML code is interpreted by the browser on the web page’s first load in order to initialize the DOM. You can use content attributes to set up the initial state on the DOM nodes created by your HTML code.
const p = document.querySelector("#neat-paragraph");
console.log(p.className); // "neato"
className on the
p element is an
“IDL attribute” for that element. “IDL” stands for “Interface Definition
Language”. The Web IDL is
the specification for IDL attributes to be implemented in web browsers.
So to sum up:
- Content attributes: The attributes you set on DOM nodes by writing them in your HTML code.
Content attributes and IDL attributes often correspond, but not always.
In the example above, we see that the content attribute is called
class but the IDL attribute is called
className. The kinds of things you can do with those
indeterminate attribute is one case of an IDL attribute
that does not have any corresponding content attribute. This means that
const cb = document.querySelector("#select-all-checkbox");
cb.indeterminate = true;
Checkboxes only have two states
The next important thing we need to understand from the HTML spec is this:
The control is never a true tri-state control, even if the element’s
indeterminateIDL attribute is set to true. The
indeterminateIDL attribute only gives the appearance of a third state.
This is good to keep in mind. Whether or not a checkbox is checked is always determined; it is always true or false. This matters when you are handling the submitted values from a form. It will never submit an indeterminate value.
A note about ARIA
I am always trying to keep my websites accessible, and you should, too.
To keep things accessible, it is important that we follow the ARIA guidelines from the W3C. They have excellent documentation!
For checkboxes, there is an
aria-checked attribute that you
could set on the checkbox. It is
strongly recommended that you don’t do this. The reason for this is that it would be really bad for
aria-checked to disagree with the actual state of the
The good news is that the value of
automatically calculated for you!
I don’t see any reason why you would need to manually set the
aria-checked attribute for a checkbox, unless you are
building one from scratch out of
Perhaps you think you need this so that you can write a CSS selector for indeterminate checkboxes.
There’s a CSS selector for that
More good news! CSS allows us to select checkboxes in any of the three states using pseudo-classes.
:checkedpseudo-class selects checkboxes that are checked.
We can use
:not(:checked)to select for checkboxes that are not checked.
:indeterminatepseudo-class selects checkboxes in an indeterminate state.
I hope you found this helpful! See the follow-up blog post where we implement an indeterminate checkbox using React and TypeScript.