Setting Custom URLs

The URL parameter to pushState and replaceState can be used to update the URL of the page without navigating. To illustrate, consider you’ve loaded “http://www.contoso.com/index.html.” Using hash changes, you can only append to the URL:

// Change to "http://www.contoso.com/index.html#about.html"

location.hash = "about.html";

But with pushState and replaceState you can point to a completely different page on your site without actually going there:

// Change to "http://www.contoso.com/about.html"

history.pushState(null, "About", "/about.html");

Make sure your server can handle all dynamic URLs you create so things like favorites still work. You can also add some data to the state object so you don’t have to parse the full URL later to restore the state:

history.pushState("about.html", "About", "/about.html");

The protocol, hostname, and port must match the current URL, but the path, query, and fragment are fair game for customization. This enables associating dynamic states with URLs that are easily backed by the server and work even when script is disabled. Ultimately, this lets you dynamically fetch and display only the data that changes from page to page while keeping the user experience intact.