DOMTokenList

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

The DOMTokenList interface represents a set of space-separated tokens. Such a set is returned by Element.classList or HTMLLinkElement.relList, and many others.

A DOMTokenList is indexed beginning with 0 as with JavaScript Array objects. DOMTokenList is always case-sensitive.

Instance properties

DOMTokenList.length Read only

An integer representing the number of objects stored in the object.

DOMTokenList.value

A stringifier property that returns the value of the list as a string.

Instance methods

DOMTokenList.item()

Returns the item in the list by its index, or null if the index is greater than or equal to the list's length.

DOMTokenList.contains()

Returns true if the list contains the given token, otherwise false.

DOMTokenList.add()

Adds the specified tokens to the list.

DOMTokenList.remove()

Removes the specified tokens from the list.

DOMTokenList.replace()

Replaces the token with another one.

DOMTokenList.supports()

Returns true if the given token is in the associated attribute's supported tokens.

DOMTokenList.toggle()

Removes the token from the list if it exists, or adds it to the list if it doesn't. Returns a boolean indicating whether the token is in the list after the operation.

DOMTokenList.entries()

Returns an iterator, allowing you to go through all key/value pairs contained in this object.

DOMTokenList.forEach()

Executes a provided callback function once for each DOMTokenList element.

DOMTokenList.keys()

Returns an iterator, allowing you to go through all keys of the key/value pairs contained in this object.

DOMTokenList.toString()

Returns the DOMTokenList.value, the space-separated values of the list as a string.

DOMTokenList.values()

Returns an iterator, allowing you to go through all values of the key/value pairs contained in this object.

Examples

In the following simple example, we retrieve the list of classes set on a <p> element as a DOMTokenList using Element.classList, add a class using DOMTokenList.add(), and then update the Node.textContent of the <p> to equal the DOMTokenList.

First, the HTML:

html
<p class="a b c"></p>

Now the JavaScript:

js
let para = document.querySelector("p");
let classes = para.classList;
para.classList.add("d");
para.textContent = `paragraph classList is "${classes}"`;

The output looks like this:

Trimming of whitespace and removal of duplicates

Methods that modify the DOMTokenList (such as DOMTokenList.add()) automatically trim any excess Whitespace and remove duplicate values from the list. For example:

html
<span class="    d   d e f"></span>
js
let span = document.querySelector("span");
let classes = span.classList;
span.classList.add("x");
span.textContent = `span classList is "${classes}"`;

The output looks like this:

Specifications

Specification
DOM
# interface-domtokenlist

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
DOMTokenList
[Symbol.iterator]
add
Multiple parameters for add()
contains
entries
forEach
item
keys
length
remove
Multiple parameters for remove()
Removes duplicates
replace
return()'s value is a boolean, not void as it used to be.
supports
toString
toggle
force parameter
Trims whitespace
value
values

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
See implementation notes.