DOMTokenList.toggle() — Methode · JavaScript-Referenz

Signatur

DOMTokenList.prototype.toggle(token, force)

Beschreibung

Die Methode toggle() der Schnittstelle DOMTokenList fügt ein Token hinzu, wenn es fehlt, und entfernt es, wenn es schon vorhanden ist. Meistens nutzt man sie über element.classList, um CSS-Klassen ein- und auszuschalten, z. B. für aufklappbare Menüs, den Dunkelmodus oder aktive Zustände.

Mit dem optionalen zweiten Parameter force wird aus dem Umschalten eine gezielte Operation: Bei true wird das Token nur hinzugefügt (wie add()), bei false nur entfernt (wie remove()). So lässt sich eine Klasse direkt an eine Bedingung koppeln, ohne ein if/else mit add und remove zu schreiben.

Der Rückgabewert gibt an, ob das Token nach dem Aufruf in der Liste steht. Das ist praktisch, um zum Beispiel ARIA-Attribute wie aria-expanded synchron zu halten.

Parameter

Name	Typ	Default	Beschreibung
$token Pflicht	string		Das umzuschaltende Token, z. B. ein Klassenname. Darf nicht leer sein und keine Leerzeichen enthalten.
$force	boolean		Wenn angegeben: `true` fügt das Token nur hinzu, `false` entfernt es nur. Ohne Angabe wird umgeschaltet.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Token nach dem Aufruf in der Liste enthalten ist, sonst false.

Beispiele

Menü per Klick auf- und zuklappen

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

button.addEventListener('click', () => {
  // Klasse umschalten und Zustand für Screenreader übernehmen
  const isOpen = menu.classList.toggle('open');
  button.setAttribute('aria-expanded', String(isOpen));
  console.log(`Menü offen: ${isOpen}`);
});

Menü offen: true Menü offen: false

Klasse mit force an eine Bedingung koppeln

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

input.addEventListener('input', () => {
  const invalid = !input.value.includes('@');
  // Statt if/else mit add()/remove()
  input.classList.toggle('error', invalid);
});

Rückgabewerte im Überblick

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

console.log(div.classList.toggle('active'));        // hinzugefügt
console.log(div.classList.toggle('active'));        // entfernt
console.log(div.classList.toggle('box', true));     // bleibt drin
console.log(div.classList.toggle('hidden', false)); // bleibt draußen
console.log(div.className);

true false true false box

Dunkelmodus speichern

const toggleDark = () => {
  const dark = document.documentElement.classList.toggle('dark');
  localStorage.setItem('theme', dark ? 'dark' : 'light');
};

// Beim Laden den gespeicherten Zustand wiederherstellen
document.documentElement.classList.toggle(
  'dark',
  localStorage.getItem('theme') === 'dark'
);
document.querySelector('#theme-switch').addEventListener('click', toggleDark);

// Wichtig · Fallstricke

Ein leerer String als token löst einen DOMException vom Typ SyntaxError aus, ein Token mit Leerzeichen (z. B. 'a b') einen InvalidCharacterError. Mehrere Klassen auf einmal umschalten geht nicht, dafür muss man toggle() mehrfach aufrufen.
Bei force zählt nur, ob der Wert truthy oder falsy ist: toggle('x', undefined) wird aber wie ein Aufruf ohne force behandelt, schaltet also um. Sicherer ist ein ausdrücklicher Boolean, z. B. Boolean(bedingung).
Tokens unterscheiden Groß- und Kleinschreibung: 'Active' und 'active' sind verschiedene Tokens.
Kompatibilität: In allen modernen Browsern verfügbar. Der Internet Explorer hat den force-Parameter ignoriert und unterstützte classList auf SVG-Elementen nicht.

Siehe auch

DOMTokenList DOMTokenList.add() DOMTokenList.remove() DOMTokenList.contains() DOMTokenList.replace() Element.classList new TaskController()