Element.classList — Eigenschaft · JavaScript-Referenz

Signatur

get Element.classList

Beschreibung

Element.classList gibt eine live DOMTokenList zurück, die die CSS-Klassen eines Elements enthält. Mit den Methoden add(), remove(), toggle(), replace() und contains() lassen sich einzelne Klassen gezielt setzen, entfernen oder prüfen. Die umständliche Bearbeitung der leerzeichengetrennten Zeichenkette in element.className entfällt damit.

Die Liste ist live: Jede Änderung am class-Attribut, egal ob über setAttribute(), className oder classList selbst, ist sofort in derselben DOMTokenList-Instanz sichtbar. Ist kein class-Attribut gesetzt oder ist es leer, erhältst du eine leere Liste mit length === 0, aber niemals null.

Die Eigenschaft ist schreibgeschützt, weil sich das DOMTokenList-Objekt selbst nicht austauschen lässt. Eine direkte Zuweisung wie el.classList = "a b" ist aber erlaubt und wirkt wie eine Zuweisung an el.classList.value, ersetzt also alle Klassen. Typische Einsätze sind Zustandswechsel in der Oberfläche (aktiv/inaktiv, offen/geschlossen), Dark-Mode-Schalter, Validierungsanzeigen und das Starten von CSS-Animationen.

Rückgabewert

Typ

DOMTokenList

Beschreibung

Eine live DOMTokenList mit den Klassen des Elements. Wichtige Mitglieder: add(...tokens), remove(...tokens), toggle(token, force?) (liefert boolean), replace(alt, neu) (liefert boolean), contains(token), item(index), length, value sowie forEach(), entries(), keys() und values().

Beispiele

Klassen hinzufügen, entfernen und prüfen

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

box.classList.add('shadow', 'rounded');   // mehrere Klassen auf einmal
box.classList.remove('rounded');

console.log(box.classList.contains('shadow')); // true
console.log(box.classList.length);             // 2
console.log(box.classList.value);              // "card shadow"
console.log([...box.classList]);               // iterierbar

true 2 card shadow ["card", "shadow"]

Menü per toggle() öffnen und schließen

const button = document.querySelector('#menu-button');
const nav = document.querySelector('#main-nav');

button.addEventListener('click', () => {
  // toggle() gibt zurück, ob die Klasse danach vorhanden ist
  const isOpen = nav.classList.toggle('is-open');
  button.setAttribute('aria-expanded', String(isOpen));
});

toggle() mit force-Parameter für Formularvalidierung

const input = document.querySelector('#email');

input.addEventListener('input', () => {
  const valid = input.validity.valid;
  // force=true fügt immer hinzu, force=false entfernt immer
  input.classList.toggle('is-invalid', !valid);
  input.classList.toggle('is-valid', valid);
});

Theme per replace() wechseln und Live-Verhalten zeigen

const root = document.documentElement;
root.className = 'theme-light';

const list = root.classList;
const replaced = list.replace('theme-light', 'theme-dark');
console.log(replaced, list.value);

// Live: Änderung über setAttribute ist sofort in list sichtbar
root.setAttribute('class', 'theme-contrast');
console.log(list.contains('theme-contrast'));

true theme-dark true

// Wichtig · Fallstricke

Keine Leerzeichen in Tokens: el.classList.add('a b') wirft einen InvalidCharacterError. Ein leerer String wirft einen SyntaxError. Mehrere Klassen übergibst du als einzelne Argumente oder mit Spread: add(...['a', 'b']).
Zuweisung ersetzt alles: el.classList = 'x' überschreibt alle vorhandenen Klassen, so wie className. Für einzelne Änderungen nimmst du add() bzw. remove().
Doppelte Einträge: add() legt keine Duplikate an, und remove() einer nicht vorhandenen Klasse erzeugt keinen Fehler.
Live-Liste beim Iterieren: Entfernst du in einer for-Schleife über Indizes Klassen, verschieben sich die Indizes. Kopiere die Liste vorher mit [...el.classList].
Browser-Kompatibilität: In allen modernen Browsern verfügbar. Ältere Browser (IE10/11) unterstützen weder mehrere Argumente bei add()/remove() noch den force-Parameter von toggle() noch replace(). Bei SVG-Elementen fehlte classList im IE ganz.
Animation neu starten: Entfernen und sofortiges Hinzufügen derselben Klasse startet eine CSS-Animation nicht neu. Dazwischen ist ein erzwungener Reflow nötig (z. B. ein Lesezugriff auf el.offsetWidth).

Siehe auch

Element.matches() Element.currentCSSZoom Element.className Element.clientLeft Element.slot