CKTIS / JavaScript
DOMTokenList: Add, remove, and toggle tokens
Change individual tokens with `add()`, `remove()`, and `toggle()`. Use the `force` argument when a condition should determine whether a token is present.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
list.add(...tokens)
list.remove(...tokens)
list.toggle(token)
list.toggle(token, force)element.classList exposes a DOMTokenList: a live, case-sensitive set of unique tokens. Editing the list updates the class attribute, and editing the attribute is reflected even through a previously saved reference to the list. DOMTokenList.add/remove/toggle are DOM methods, not ECMAScript features; the runtime must provide the relevant DOM APIs.
add() inserts the specified tokens without creating duplicates. remove() deletes the specified tokens and ignores those that are absent. Both methods accept multiple tokens as separate arguments and return undefined.
toggle(token) flips membership for one token: it adds an absent token or removes a present one. In toggle(token, force), true ensures presence and false ensures absence. Both forms return whether the token is present after the call, not whether anything changed. Use toggle(token, condition) when membership should track a boolean condition.
In all three methods, an empty token throws a DOMException named SyntaxError, and a token containing ASCII whitespace throws a DOMException named InvalidCharacterError. Pass list.add("a", "b"), not list.add("a b"): arguments are not split into tokens.
Examples
{
function createExampleElement() {
if (typeof document !== "undefined") {
return document.createElement("div");
}
// Without a DOM, model only the operations used here with valid tokens.
const tokens = new Set();
return {
classList: {
add(...values) {
for (const value of values) tokens.add(value);
},
remove(...values) {
for (const value of values) tokens.delete(value);
},
toggle(value, force = !tokens.has(value)) {
if (force) tokens.add(value);
else tokens.delete(value);
return tokens.has(value);
}
},
getAttribute(name) {
return name === "class" ? [...tokens].join(" ") : null;
}
};
}
const element = createExampleElement();
const list = element.classList;
list.add("card", "pending", "card");
list.remove("pending", "missing");
console.log(list.toggle("active"));
console.log(list.toggle("active"));
console.log(list.toggle("ready", true));
console.log(list.toggle("active", false));
console.log(element.getAttribute("class"));
}Result
true false true false card ready
Run this in a browser console. The element is not attached to the page. The first two results show `active` being added and removed; the next two show that `ready` is present and `active` stays absent. The final line is the value of the `class` attribute.
Related lessons
- JavaScript · Lesson 7 · Advanced · Version: 4
- JavaScript · Lesson 32 · Intermediate · Version: 3
- JavaScript · Lesson 34 · Intermediate · Version: 3
- JavaScript · Lesson 43 · Intermediate · Version: 3