DOMTokenList.add() — Methode · JavaScript-Referenz

Signatur

DOMTokenList.prototype.add(...tokens)

Beschreibung

Mit add() fügst du einer DOMTokenList neue Tokens hinzu. Meistens geht es dabei um element.classList, also um CSS-Klassen. Die Methode funktioniert aber genauso bei anderen Token-Listen wie link.relList, iframe.sandbox oder output.htmlFor. Tokens, die schon in der Liste stehen, fügt sie kein zweites Mal ein. Doppelte Einträge entstehen also nie.

Du kannst beliebig viele Tokens auf einmal übergeben, zum Beispiel classList.add("a", "b", "c"). Das ist deutlich robuster, als den className-String selbst zu bearbeiten: Andere Klassen bleiben erhalten, und um Leerzeichen oder Duplikate musst du dich nicht kümmern.

Nach dem Aufruf aktualisiert der Browser das zugehörige Attribut, bei classList also class. Dabei werden Duplikate entfernt und die Tokens neu geordnet. Die Methode gibt nichts zurück. Deshalb kannst du Aufrufe nicht verketten.

Parameter

Name	Typ	Default	Beschreibung
$...tokens Pflicht	string		Ein oder mehrere Tokens, die hinzugefügt werden sollen. Werte, die keine Strings sind, werden in Strings umgewandelt. Leere Strings und Tokens mit Leerzeichen sind nicht erlaubt.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Eine oder mehrere Klassen hinzufügen

const box = document.createElement("div");
box.className = "card";

box.classList.add("active");
box.classList.add("shadow", "rounded", "active"); // "active" ist schon da und wird ignoriert

console.log(box.className);

card active shadow rounded

Klassen aus einem Array per Spread hinzufügen

const button = document.querySelector("button");
const variants = ["btn", "btn-primary", "btn-lg"];

button.classList.add(...variants);
console.log(button.classList.contains("btn-primary"));

true

Fehlerbehandlung bei ungültigen Tokens

const el = document.createElement("span");

try {
  el.classList.add("is valid"); // enthält ein Leerzeichen
} catch (err) {
  console.log(err.name);
}

try {
  el.classList.add("");
} catch (err) {
  console.log(err.name);
}

InvalidCharacterError SyntaxError

Beim Scrollen eine Klasse setzen (Praxisfall)

const header = document.querySelector("header");

window.addEventListener("scroll", () => {
  if (window.scrollY > 50) {
    header.classList.add("sticky"); // wiederholte Aufrufe sind unschädlich
  } else {
    header.classList.remove("sticky");
  }
}, { passive: true });

// Wichtig · Fallstricke

Ungültige Tokens: Bei einem leeren String wirft die Methode eine DOMException vom Typ SyntaxError. Enthält ein Token Leerzeichen (Space, Tab, Zeilenumbruch), ist es ein InvalidCharacterError. add(\"a b\") fügt also nicht zwei Klassen hinzu. Übergib stattdessen add(\"a\", \"b\").
Keine Verkettung: Die Methode gibt undefined zurück. Ein Ausdruck wie el.classList.add(\"a\").add(\"b\") löst deshalb einen TypeError aus.
Attribut wird neu geschrieben: Nach dem Aufruf wird das class-Attribut neu serialisiert. Dabei werden Duplikate und überzählige Leerzeichen entfernt, auch solche, die schon vorher im Attribut standen. Das kann einen MutationObserver auslösen, selbst wenn kein neues Token dazukommt.
Groß-/Kleinschreibung: Tokens werden mit Beachtung der Groß-/Kleinschreibung verglichen. \"Active\" und \"active\" gelten als verschiedene Tokens.
SVG: Bei SVG-Elementen verwende classList statt className. Dort ist className ein SVGAnimatedString und kein normaler String.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Der Internet Explorer hat mehrere Argumente nicht unterstützt und auf SVG-Elementen gar kein classList angeboten.

Siehe auch

DOMTokenList DOMTokenList.remove() DOMTokenList.toggle() DOMTokenList.contains() DOMTokenList.replace() Element.classList Element.className