Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

DOMTokenList: checking and toggling tokens

`contains()` checks whether a token is present without changing the list. `toggle()` flips membership or sets it with `force`, then reports whether the token is present.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

tokens.contains(token)
tokens.toggle(token)
tokens.toggle(token, force)

DOMTokenList.contains/toggle refers to two instance methods on a token list. For example, element.classList gives you a live list backed by the element’s class attribute. These are DOM APIs, not part of ECMAScript 2024. Support depends on the runtime. The example uses the native DOM in a browser and a small stand-in in Node.js for the valid tokens shown.

tokens.contains(token) returns true if the exact token is present and false otherwise. It does not change the list, ignores no differences in case, and does not search for substrings. An empty string or a string containing ASCII whitespace returns false.

tokens.toggle(token) adds an absent token or removes a present one. tokens.toggle(token, true) ensures it is present; tokens.toggle(token, false) ensures it is absent. The return value tells you whether the token is present afterward, not whether anything changed. To keep a class in sync with a boolean condition, use tokens.toggle(token, condition). Passing undefined as force is the same as omitting it: tokens.toggle(token, undefined) flips membership. Any other supplied force value is converted to a boolean: the string "false" becomes true, not false.

toggle() takes one token at a time. An empty string throws a DOMException named SyntaxError; ASCII whitespace in the token throws one named InvalidCharacterError, even when force is false. Pass the class name without the selector dot: "active", not ".active".

Examples

{
  function createExampleElement(initialClass) {
    if (typeof document !== "undefined") {
      const element = document.createElement("div");
      element.className = initialClass;
      return element;
    }

    // Node.js has no browser DOM. This stand-in handles the valid tokens used below.
    const classes = new Set([initialClass]);
    return {
      get className() {
        return [...classes].join(" ");
      },
      classList: {
        contains(token) {
          return classes.has(token);
        },
        toggle(token, force) {
          const present = force === undefined ? !classes.has(token) : Boolean(force);
          if (present) classes.add(token);
          else classes.delete(token);
          return present;
        },
      },
    };
  }

  const element = createExampleElement("panel");
  const tokens = element.classList;

  console.log(tokens.contains("active"));
  console.log(tokens.toggle("active"));
  console.log(tokens.toggle("active"));
  console.log(tokens.toggle("active", true));
  console.log(tokens.toggle("active", true));
  console.log(tokens.toggle("active", false));
  console.log(element.className);
}

Result

false
true
false
true
true
false
panel

The two calls without `force` add and then remove `active`. Both calls with `true` return `true`, even though the second changes nothing. The call with `false` removes `active`, leaving only `panel`.

Related lessons

  • JavaScript · Lesson 31 · Intermediate · Version: 3

Sources