Location.replace() — Methode · JavaScript-Referenz

Signatur

Location.prototype.replace(url)

Beschreibung

location.replace() lädt die Ressource an der übergebenen URL und ersetzt dabei den aktuellen Eintrag im Sitzungsverlauf (History). Anders als bei location.assign() oder beim Setzen von location.href entsteht kein neuer Verlaufseintrag. Die aktuelle Seite ist danach also nicht mehr über den Zurück-Button des Browsers erreichbar.

Typische Einsatzfälle sind Weiterleitungen, bei denen die Ausgangsseite im Verlauf keinen Sinn ergibt, zum Beispiel nach dem Login oder Logout, nach dem Absenden eines Formulars (damit ein „Zurück“ das Formular nicht erneut abschickt), bei Zwischenseiten wie „Sie werden weitergeleitet …“ oder bei clientseitigen Umleitungen von veralteten URLs.

Die URL darf absolut oder relativ sein. Relative URLs werden gegen die URL des Dokuments aufgelöst, in dem die Methode aufgerufen wird. Die Navigation läuft asynchron: Code nach dem Aufruf wird zunächst weiter ausgeführt, bis der Browser die Seite verlässt.

Wenn du den Verlaufseintrag nur ändern willst, ohne die Seite neu zu laden (etwa in Single-Page-Apps), nimm stattdessen history.replaceState().

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string \| URL		Ziel-URL, absolut oder relativ. Wird intern in einen String umgewandelt, deshalb funktionieren auch `URL`-Objekte.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Die Navigation wird angestoßen, und die aktuelle Seite wird danach entladen.

Beispiele

Einfache Weiterleitung ohne Verlaufseintrag

// Alte URL dauerhaft auf die neue Seite umleiten
if (location.pathname === '/alte-seite.html') {
  location.replace('/neue-seite.html');
}

Weiterleitung nach erfolgreichem Login

const loginForm = document.querySelector('#login');

loginForm.addEventListener('submit', async (event) => {
  event.preventDefault();
  const response = await fetch('/api/login', {
    method: 'POST',
    body: new FormData(loginForm),
  });

  if (response.ok) {
    // Mit „Zurück“ soll man nicht wieder auf der Login-Seite landen
    const params = new URLSearchParams(location.search);
    const ziel = params.get('redirect') ?? '/dashboard';
    // Nur Ziele auf der eigenen Domain zulassen (Schutz vor offener Weiterleitung)
    const url = new URL(ziel, location.origin);
    location.replace(url.origin === location.origin ? url : '/dashboard');
  }
});

Unterschied zu assign() im Vergleich

console.log('Verlaufslänge vorher:', history.length);

// Legt einen NEUEN Verlaufseintrag an – „Zurück“ führt hierher zurück:
// location.assign('/seite-b');

// Ersetzt den aktuellen Eintrag – history.length bleibt gleich:
location.replace('/seite-b');

Verlaufslänge vorher: 3

Weiterleitung auf HTTPS erzwingen

if (location.protocol === 'http:' && location.hostname !== 'localhost') {
  const sicher = new URL(location.href);
  sicher.protocol = 'https:';
  location.replace(sicher);
}

// Wichtig · Fallstricke

Sicherheit – offene Weiterleitung: Übernimm Ziel-URLs niemals ungeprüft aus Query-Parametern oder Benutzereingaben. Angreifer können sonst auf fremde Phishing-Seiten umleiten. Prüfe die origin mit new URL(), oder arbeite mit einer Liste erlaubter Ziele.
XSS über javascript:-URLs: Wenn url mit javascript: beginnt, wird der enthaltene Code ausgeführt. Nicht vertrauenswürdige Werte müssen deshalb vorher auf http: oder https: geprüft werden.
Eine ungültige URL löst einen SyntaxError (DOMException) aus. Wird aus einem fremden Ursprung heraus navigiert, der dazu nicht berechtigt ist (z. B. aus einem Sandbox-iframe), gibt es einen SecurityError.
Code nach dem Aufruf läuft noch weiter. Brich die Ausführung bei Bedarf mit return ab.
Für echte, dauerhafte Weiterleitungen sind serverseitige Umleitungen (HTTP 301/308) besser für Suchmaschinen und Performance.
Die Methode wird von allen Browsern seit Langem unterstützt.

Siehe auch

Location.assign() Location.reload() Location.href Location History.replaceState() History.pushState() Location.toString()