How to update the browser URL without refreshing the page using the vanilla JS History API
You can use the window.location.href
property to update the browser URL.
window.location.href = 'http://my-new-url.com';
But using this approach causes the page to reload. What if you want to update the URL without refreshing the page?
Today, let’s take a look at the History API.
The History API
The History API is a set of methods on the history
object that can be used to manipulate the history—the thing that’s accessed by the forward and backward buttons—of the browser.
It works in all modern browsers, and back to IE 10.
The history.pushState()
method
The history.pushState()
method can be used to push a new entry into the browser’s history—and as a result, update the displayed URL—without refreshing the page.
It accepts three arguments:
state
, an object with some details about the URL or entry in the browser’s history.title
, which is supoposed to be what thedocument.title
property should be (more on this shortly).url
, the URL to add to the browser’s history.
An example
This method is mostly useful with single page apps, where you load content with JavaScript but want to update the URL to match.
(I use it in my Smooth Scroll plugin to update the URL without triggering a hard page jump down to anchored elements.)
For example, let’s say you were on the homepage, and wanted to change the URL to reflect the about page. You might do something like this:
history.pushState({pageID: 'about'}, 'About', '/about');
If you want, you can jump over to the homepage of my site, copy/paste that into the console tab in developer tools, and run it.
Some gotchas
Like many JavaScript methods, the history.pushState()
method has a few gotchas.
Some browsers impose a 640,000 character limit on the state
object. If you need to pass data along from one view to the next, and that data is large, you should us an empty object here and save that data with localStorage
or sessionStorage
instead.
The title
attribute is required, but ignored by all browsers. It probably shouldn’t exist at all, but it shipped with the API originally and can’t be removed without breaking sites that use it.
Based on both of these things, the most important argument, url
, should probably be first, since it’s the only one you really need to do what you want to do. But for some reason, it’s last.
Regardless, the history.pushState()
method is incredibly useful for certain situations.
Other things you can do with the History API
Tomorrow, we’ll take a look at some other things you can do with the History API.
Most importantly, we’ll learn how to detect URL updates and access the browser history (super important if you’re trying to do routing with JavaScript).