JavaScript Reference ยท DOM: Document and Elements
Element.classList
Reference for Element.classList: add, remove, toggle, replace and test CSS classes with the DOMTokenList API, including the force argument and error cases.
The classList property gives you a live DOMTokenList for the class attribute of an element. Instead of splitting and joining a string by hand, you call methods such as add(), remove() and toggle(). Each change updates the attribute immediately, and the browser takes care of spacing and duplicates.
Changing classes is the cleanest way to restyle an element from JavaScript: the style rules stay in your CSS, and the script only switches states.
button.classList.add("active"); button.classList.toggle("open");
Try it
Syntax
element.classList.add(token1, token2, ...) element.classList.remove(token1, token2, ...) element.classList.toggle(token, force) element.classList.replace(oldToken, newToken) element.classList.contains(token)
| Member | Description |
|---|---|
add(...tokens) |
Adds one or more classes. Classes that are already present are ignored. Returns undefined. |
remove(...tokens) |
Removes one or more classes. Missing classes are ignored. Returns undefined. |
toggle(token, force) |
Adds the class if it is missing, removes it if it is present. With force, true only adds and false only removes. Returns true if the class is present afterwards, otherwise false. |
replace(oldToken, newToken) |
Swaps one class for another. Returns true if oldToken existed and was replaced, otherwise false and nothing changes. |
contains(token) |
Returns true if the class is present. |
item(index) |
Returns the class at the position, or null. Same as list[index]. |
length |
Number of classes. |
value |
The raw attribute string. Also settable. |
The list is iterable, and it has forEach(), keys(), values() and entries().
Exceptions: SyntaxError (DOMException) if a token is an empty string, and InvalidCharacterError if it contains whitespace.
Usage notes
- Live object. The same
classListreflects later changes to theclassattribute, whether they come fromclassName,setAttribute()or other code. - One class per argument.
add("a b")throws because of the space. Passadd("a", "b"), or spread an array:add(...names). - Use
forcefor conditions.el.classList.toggle("error", isInvalid)is shorter and clearer than anif/elsethat adds or removes. - Order and duplicates.
add()appends to the end of the attribute. The list never holds the same class twice, but it also does not sort. - Assigning to
classList. Writingel.classList = "a b"sets the attribute value, but most code prefersclassNameorsetAttribute("class", ...)for clarity. - SVG.
classListworks on SVG elements too. Prefer it overclassName, which is an object there. - Cheaper than inline styles. Switching a class keeps the look in the style sheet, makes transitions easy and lets you override states with specificity rules.
Browser support
Supported in all current browsers, including the multi-argument forms of add() and remove() and the force argument of toggle().
Related
HTMLElement.styleโ inline stylesElement.getAttribute()andsetAttribute()โ theclassattribute as a stringElement.matches()โ test a class with a selector- Lesson: Styles and classes