HTML Academy · Lesson

pushState and replaceState

Update the browser URL without a full page reload.

pushState and replaceState is a free HTML Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the HTML Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The History API

The History API lets a page change the URL displayed in the address bar without triggering a full navigation. Combined with client-side rendering, this powers Single-Page Applications that feel native without sacrificing bookmarkable URLs.

pushState

history.pushState(state, "", url) adds a new entry to the browser history. The URL in the address bar updates immediately; no network request is made. The user can navigate back to the previous entry with the browser's back button.

history.pushState({ view: "settings" }, "", "/settings");

The state Argument

The first argument is arbitrary serializable data attached to the entry. Read it back later via history.state or in popstate events. Use it to pass UI state (which tab was open, scroll position) so navigating back can restore the exact view.

The title Argument

The second argument is the entry title. In practice, all modern browsers ignore it — set document.title = "..." directly to change the title. Pass an empty string as a convention; it has no effect.

The url Argument

The third argument is the new URL. Relative URLs resolve against the current page; the new URL must be same-origin (cross-origin throws SecurityError). Browsers do not fetch the URL — pushState only updates the address bar and history.

replaceState

history.replaceState(state, "", url) replaces the current history entry instead of adding a new one. Use when you want to update the URL without creating a new back-navigation step (e.g., updating a filter query string).

// Update query string in place
const url = new URL(location);
url.searchParams.set("filter", "open");
history.replaceState(null, "", url);

Use Cases for pushState

SPA route changes (clicking a navigation link without full reload), modal open (so back button closes the modal), step transitions in a wizard. Each meaningful state should be a new history entry, so the back button does what users expect.

Use Cases for replaceState

Filter/sort/pagination updates that should not pollute history, redirecting after a partial form completion, updating tracking parameters without creating navigable entries. The user pressing back skips over these "intermediate" states.

Update the View After pushState

pushState only changes the URL — your code must update the DOM separately. The pattern is: render new content, then call pushState. The two together produce the SPA experience.

function navigate(path) {
  renderPage(path);
  history.pushState(null, "", path);
  window.scrollTo(0, 0);
}

Title and Meta Updates

Update document.title and og:title meta tags after navigation so social sharing and browser tab titles reflect the current view. Forgetting this leaves the original title on subsequent shares — a subtle but common SPA bug.

Initial pushState on Page Load

Calling pushState before the user has navigated overwrites the initial entry. To attach state to the page's first entry, use replaceState instead — adds the state without altering history depth.

Security Constraint

pushState URLs must be same-origin. Attempting to pushState to https://evil.com throws SecurityError. This prevents pages from spoofing the address bar to make users think they are on a different site.

Knowledge Check

What does history.replaceState do that history.pushState does not?

Summary

pushState adds a new history entry without a page reload — the foundation of SPA routing. replaceState updates the current entry in place for cosmetic URL changes. Both require same-origin URLs and ignore the title argument. Always update the DOM separately and remember to update document.title and meta tags after navigation.

Frequently asked questions

Is the “pushState and replaceState” lesson free?

Yes — the full text of “pushState and replaceState” is free to read here on the web, and the HTML Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the HTML Academy course, upgrade to CoddyKit PRO.

What will I learn in “pushState and replaceState”?

Update the browser URL without a full page reload. You practise HTML Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start HTML Academy?

No prior experience is required. HTML Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “pushState and replaceState” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this HTML Academy lesson?

Yes. Every HTML Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to HTML Academy