Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
button.classList.add("active");
button.classList.toggle("open");

Try it

add, remove, toggle and contains
replace, force and iteration

Syntax

JavaScript
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 classList reflects later changes to the class attribute, whether they come from className, setAttribute() or other code.
  • One class per argument. add("a b") throws because of the space. Pass add("a", "b"), or spread an array: add(...names).
  • Use force for conditions. el.classList.toggle("error", isInvalid) is shorter and clearer than an if/else that 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. Writing el.classList = "a b" sets the attribute value, but most code prefers className or setAttribute("class", ...) for clarity.
  • SVG. classList works on SVG elements too. Prefer it over className, 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().