DOMTokenList.replace() — Methode · JavaScript-Referenz

Signatur

DOMTokenList.prototype.replace(oldToken, newToken)

Beschreibung

Die Methode replace() tauscht in einer DOMTokenList ein vorhandenes Token gegen ein neues aus. In der Praxis nutzt man sie fast immer über element.classList, um eine CSS-Klasse in einem Schritt durch eine andere zu ersetzen, etwa beim Wechsel von theme-light zu theme-dark oder von is-loading zu is-done.

Im Unterschied zur Kombination aus remove() und add() bleibt die Position des Tokens in der Liste erhalten. Außerdem liefert die Methode einen boolean: true, wenn oldToken vorhanden war und ersetzt wurde, sonst false. Fehlt oldToken, wird nichts hinzugefügt – anders als bei toggle() oder add().

Enthält die Liste newToken schon, wird oldToken nur entfernt. So entstehen keine doppelten Einträge. Die Methode funktioniert auch bei anderen DOMTokenList-Eigenschaften wie relList von <a>/<link> oder part.

Parameter

Name	Typ	Default	Beschreibung
$oldToken Pflicht	string		Das Token, das ersetzt werden soll, z. B. ein Klassenname. Darf weder leer sein noch Leerzeichen enthalten.
$newToken Pflicht	string		Das neue Token, das an die Stelle von `oldToken` tritt. Es gelten dieselben Einschränkungen: nicht leer, keine Leerzeichen.

Beispiele

CSS-Klasse austauschen

const box = document.createElement('div');
box.className = 'card is-loading shadow';

const ersetzt = box.classList.replace('is-loading', 'is-done');
console.log(ersetzt);
console.log(box.className); // Position bleibt erhalten

true card is-done shadow

Rückgabewert nutzen: Klasse nicht vorhanden

const btn = document.createElement('button');
btn.className = 'btn';

// replace() fügt nichts hinzu, wenn das alte Token fehlt
if (!btn.classList.replace('btn-primary', 'btn-secondary')) {
  btn.classList.add('btn-secondary');
}
console.log(btn.className);

btn btn-secondary

Theme-Umschalter mit replace()

const root = document.documentElement;
root.classList.add('theme-light');

const toggleTheme = () => {
  // Versucht zuerst hell zu dunkel, sonst dunkel zu hell
  root.classList.replace('theme-light', 'theme-dark') ||
    root.classList.replace('theme-dark', 'theme-light');
  console.log(root.className);
};

toggleTheme();
toggleTheme();

theme-dark theme-light

Neues Token existiert bereits: Duplikate werden vermieden

const el = document.createElement('span');
el.className = 'a b c';

el.classList.replace('a', 'c');
console.log(el.className);

c b

// Wichtig · Fallstricke

Ausnahmen: Ist einer der Parameter ein leerer String, wirft die Methode einen SyntaxError (DOMException). Enthält ein Parameter Leerzeichen (Space, Tab, Zeilenumbruch), wird ein InvalidCharacterError geworfen. Klassennamen aus Benutzereingaben deshalb vorher prüfen.
Kein Hinzufügen: Anders als toggle() fügt replace() nichts hinzu, wenn oldToken fehlt. Deshalb den Rückgabewert auswerten.
Groß- und Kleinschreibung: Tokens werden mit exakter Schreibweise verglichen. 'Active' und 'active' sind verschiedene Tokens.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt (Chrome 61+, Firefox 49+, Safari 10.1+, Edge 17+). Ältere Versionen (Safari/Chrome vor 2020) gaben teils undefined statt eines boolean zurück. Der Internet Explorer unterstützt die Methode nicht. Dort remove() und add() als Ersatz nutzen.
Nur bei gültigen Tokens: Bei einer DOMTokenList mit festgelegten gültigen Werten (z. B. relList) prüft replace() keine Gültigkeit. Dafür gibt es supports().

Siehe auch

DOMTokenList DOMTokenList.add() DOMTokenList.remove() DOMTokenList.toggle() DOMTokenList.contains() Element.classList new ToggleEvent()