Your browser creates history entries when you navigate around the web. These entries are used when you want to go back or if you visited a page before and forget what it was called.
To send a user back to the previous page in their history you can use
You can also add, remove or edit history entries with two main methods,
They both achieve similar goals, both methods will let the user share or bookmark the current page.
The main difference between them is the experience a user will have when using their history afterwards, for instance when they press 'back' or when they browse their history.
window.history.pushState() adds new entries to the users' history.
If you were to use
pushState() three times, a user would have to press 'back' in their browser three times to get to where they started.
If your browser's history were implemented using the History Web API, this method would be used when users click a regular link to visit a new page.
When to use pushSate
- the majority of the content in page has been updated
- if you would give the page a different
Examples of pushState
Note on accessibility: The example libraries take care to re-introduce some of the behaviours that the browser has by default such as setting the focus and scroll position. If you decide to use
pushState without a router, ensure you take this into account.
window.history.replaceState() changes the current history entry.
If you were to use
replaceState three times, a user would only have to press back once.
You may decide that you want to keep a user's state the same when they go 'back' to a page, but without adding or changing the history.
In these cases you could consider
When to use replaceState
- most of the content on the page is the same
- you want to keep a component in the same state it was when a user decides to come 'back' to the page. (See accordions and tabs)
- the user's action changes the shape of the data, for example re-ordering a data table or filtering a data table.
You'll be using
replaceState more often, since it tends to work better with components.
Examples of replaceState
Update: Thanks to Adam Silver for a correction around internal anchor links 🙂
Did I miss something, or there a different way of using this API? Send me a tweet @nickcolley