liveBook · Manning

History.replaceState()

As explained in Vanilla Web

A History API method that replaces the current session-history entry and can change the displayed URL without loading a new document.

Use history.replaceState() when a same-document router needs to change the current URL without adding another entry to session history. Unlike history.pushState(), which adds an entry, replaceState() updates the current one. Choose it when Back should not return to the URL being corrected. section 10.3.6 section 11.2

Replace a temporary route after saving

After saving settings, navigate to /settings/saved with a replace option. The saved route takes the place of the temporary route rather than adding another stop for Back. The same choice works when removing ?page=1 or redirecting /login to /account after authentication. section 11.2

In a History API router, changing the URL is not the rendering step. replaceState() does not fire popstate, so call the route renderer after replacing the entry. Keep a popstate listener for later Back and Forward traversal. If the Navigation API is available, a navigation helper can instead use navigation.navigate() with history set to "replace" and let the normal navigation handler render. section 10.3.6 section 11.2

function goTo(url, { replace = false, state } = {}) {
  const target = new URL(url, location.href);

  if (target.origin !== location.origin) {
    // External URL: hand off to the browser. The current document
    // is about to be unloaded, so the returned promise will never
    // resolve in this context. We return a resolved promise to keep
    // the function's return type consistent for callers that don't
    // await it.
    location.href = target.href; #1
    return Promise.resolve();
  }

  const routeUrl = target.pathname + target.search + target.hash;

  if ("navigation" in globalThis) {
    return navigation.navigate(routeUrl, { #2
      history: replace ? "replace" : "push", #2
      state #2
    }).finished; #2
  }

  if (replace) { #3
    history.replaceState(state ?? null, "", routeUrl); #3
  } else { #3
    history.pushState(state ?? null, "", routeUrl); #3
  } #3

  renderFromLocation(); #4
  return Promise.resolve(); #5
}

The goTo() helper keeps the replace-or-push decision in one place. Its History API fallback calls history.replaceState(state ?? null, "", routeUrl) for replacement, then renders from the updated location; external URLs are handed to the browser. section 11.2

Keep native links as the baseline for navigation. A History API fallback must handle link clicks separately and leave external links, downloads, modifier-key clicks, and hash jumps to the browser. Replacing an entry does not supply those link behaviors or a unified navigation event. section 10.3.6

How Vanilla Web covers it

How deep it goes
Shows the method inside a navigation helper and explains the required render call, but does not explore browser internals.
Examples
Uses removal of ?page=1, a post-authentication redirect, and replacement of a temporary route after saving.
What it assumes
Assumes familiarity with URLs, links, and route rendering while explaining when replacement differs from adding a history entry.
What you can do after
Apply it via the History API to replace a route, then render explicitly so the displayed page matches the URL.
How it connects
Connects session history to pushState(), popstate, same-document routing, and the Navigation API.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Vanilla Web. The section links point to the parts of the book it draws on.