DOMTokenList

The DOMTokenList interface represents a set of space-separated tokens. Such a set is returned by Element.classList (en-US), HTMLLinkElement.relList (en-US), HTMLAnchorElement.relList (en-US), HTMLAreaElement.relList (en-US), HTMLIframeElement.sandbox, or HTMLOutputElement.htmlFor. It is indexed beginning with 0 as with JavaScript Array objects. DOMTokenList is always case-sensitive.

Properties

DOMTokenList.length Read only
Is an integer representing the number of objects stored in the object.
DOMTokenList.value (en-US)
The value of the list as a DOMString (en-US).

Methods

DOMTokenList.item() (en-US)
Returns an item in the list by its index (returns undefined if the number is greater than or equal to the length of the list).
DOMTokenList.contains() (en-US)
Returns true if the list contains the given token, otherwise false.
DOMTokenList.add() (en-US)
Adds the given token to the list.
DOMTokenList.remove() (en-US)
Removes the specified token from the list.
DOMTokenList.replace() (en-US)
Replaces an existing token with a new token.
DOMTokenList.supports() (en-US)
Returns true if a given token is in the associated attribute's supported tokens.
DOMTokenList.toggle() (en-US)
Removes a given token from the list and returns false. If token doesn't exist it's added and the function returns true.
DOMTokenList.entries() (en-US)
Returns an iterator (en-US) allowing you to go through all key/value pairs contained in this object.
DOMTokenList.forEach() (en-US)
Executes a provided function once per DOMTokenList element.
DOMTokenList.keys() (en-US)
Returns an iterator (en-US) allowing you to go through all keys of the key/value pairs contained in this object.
DOMTokenList.values() (en-US)
Returns an iterator (en-US) 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> (en-US) element as a DOMTokenList using Element.classList (en-US), add a class using DOMTokenList.add() (en-US), and then update the Node.textContent (en-US) of the <p> to equal the DOMTokenList.

First, the HTML:

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

Now the JavaScript:

var para = document.querySelector("p");
var 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() (en-US)) automatically trim any excess whitespace and remove duplicate values from the list. For example:

<span class="    d   d e f"></span>
var span = document.querySelector("span");
var classes = span.classList;
span.classList.add("x");
span.textContent = 'span classList is "' + classes + '"';

The output looks like this:

Specifications

Specification Status Comment
DOM
The definition of 'DOMTokenList' in that specification.
Living Standard Initial definition

Browser compatibility

BCD tables only load in the browser

See Also