The DOMTokenList
interface represents a set of space-separated tokens. Such a set is returned by Element.classList
, HTMLLinkElement.relList
, HTMLAnchorElement.relList
, HTMLAreaElement.relList
, 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
- The value of the list as a
DOMString
.
Methods
DOMTokenList.item()
- 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()
- Returns
true
if the list contains the given token, otherwisefalse
. DOMTokenList.add()
- Adds the given token to the list.
DOMTokenList.remove()
- Removes the specified token from the list.
DOMTokenList.replace()
- Replaces an existing token with a new token.
DOMTokenList.supports()
- Returns
true
if a given token is in the associated attribute's supported tokens. DOMTokenList.toggle()
- 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()
- Returns an
iterator
allowing you to go through all key/value pairs contained in this object. DOMTokenList.forEach()
- Executes a provided function once per
DOMTokenList
element. DOMTokenList.keys()
- Returns an
iterator
allowing you to go through all keys of the key/value pairs contained in this object. 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:
<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()
) 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
DOMSettableTokenList
(object that extendsDOMTokenList
with settable .value property)