History API: pushState() and popState

Syntax

history.pushState(state, title, url)
window.addEventListener("popstate", callback)

Examples

function navigateTo(path) {
  history.pushState({ path }, "", path);
  renderPage(path); // your own function to update the visible content
}

navigateTo("/about"); // URL changes to /about, no reload happens

window.addEventListener("popstate", (event) => {
  const path = event.state ? event.state.path : "/";
  renderPage(path); // re-render based on the restored state
});

// Note: pushState() itself does NOT trigger popstate -
// only actual browser back/forward navigation does

Best practices

• Use pushState() for genuine navigation events that should be added to history - use replaceState() instead when updating the URL without adding a new back-button entry
• Always store enough state in pushState()'s first argument to correctly restore the view on popstate, rather than only relying on parsing the URL
• Remember popstate only fires on actual browser navigation (back/forward buttons) - calling pushState() yourself does not trigger it
• Consider a routing library for anything beyond simple navigation - hand-rolled routers can miss edge cases like nested routes or query parameters

At a glance

Purpose

Application logic and interaction

File extension

.js · .mjs

Runs in

Browsers and JavaScript runtimes

Usually used with

HTML, CSS and Web APIs

Specifications & further reading

• ECMAScript specification

Related JavaScript documentation