history.pushState() Fundamentals
What you'll learn: How to add new entries to the browser's history without reloading the page or making server requests.
The Core Idea
history.pushState() lets you add a new entry to the browser's history stack programmatically, just as if the user clicked a link—but without the page reload. This is the foundation of modern single-page applications (SPAs) where content changes dynamically but the URL still updates to reflect what the user is viewing.
Think of it like adding a bookmark to your reading history. You mark where you are without actually closing and reopening the book.
How It Works
The method takes three parameters:
history.pushState(state, unused, url);
- state: A JavaScript object containing any data you want to associate with this history entry (retrieved later if the user navigates back)
- unused: Historically a title parameter, but browsers ignore it—just pass an empty string
- url: The new URL to display in the address bar (must be same-origin)
Basic Example
// Add a new history entry
history.pushState(
{ page: 'about', id: 123 },
'',
'/about'
);
// The URL bar now shows "/about" but the page didn't reload!
After calling pushState(), the browser's back button becomes active. The page content doesn't change automatically—you're responsible for updating the DOM to match the new URL.
What Actually Happens
When you call pushState(), the browser:
- Adds a new entry to the history stack
- Updates the address bar
- Does not trigger navigation or a page load
- Enables the back button if it wasn't already
Key Takeaway: history.pushState() updates the URL and adds to browser history without reloading the page, giving you full control over navigation in dynamic web applications.