navigation API

Navigation API formerly known as the app history API provides an interface for navigations and session history, especially useful for SAPs.

Developers have been complaining that the current navigation and history APIs are fragile, clunky and hard to understand. navigation API solve this by providinga new interface that is easy for developers to use and understand. Some parts of the platform, e.g. accessibility technology, do not have good visibility into single-page navigations.

This API will enable developers to easily convert cross-document navigations into single-page app same-document ones. It will also provide events for notifying the application about navigations and traversals, which they can use to synchronize application or UI state. In particular, it will allow analytics (first- or third-party to watch for navigations, including gathering timing information about how long they took.

This API doesn't allow web applications to intercept user-initiated navigations in a way that would trap the user (e.g., disabling the URL bar or back button).Nor add support for multiple routers on a single page. It doesn't Handle the case where the Android back button is being used as a "close signal"; instead, that's best handled by a separate API.

The navigation object:

navigation is exposed on the global scope with the below attributes:


Let us see some of the important functionalities of this API.


This contains all the NavigationHistoryEntry which has the below attributes



const entry = navigation.entries()[navigation.currentEntry.index];
key: '2f64f187-3671-4f43-844d-c5bea322e159',
id: 'f2caf453-38a1-4401-b915-83f71eba8d42',
url: '',
index: 0,
sameDocument: true

navigate event:


event.transitionWhile(newNavigationAction, { focusReset: "manual" })

event.transitionWhile(newNavigationAction, { scrollRestoration: "manual" })

Converts this navigation into a same-document navigation to the destination URL.

Examples from the spec:

// SPA routing
navigation.addEventListener("navigate", e => {
if (!e.canTransition || e.hashChange || e.downloadRequest !== null) {

if (routesTable.has(e.destination.url)) {
const routeHandler = routesTable.get(e.destination.url);
// page-supplied "back"
backButton.addEventListener("click", () => {
if (navigation.entries()[navigation.currentEntry.index - 1]?.url === "/cart") {
} else {
// If the user arrived here by typing the URL directly:
navigation.navigate("/cart", { history: "replace" });

navigate and reload:

// Performs a navigation to the given URL, but replace the current history entry
// instead of pushing a new one.
// (equivalent to `location.replace(url)`)
navigation.navigate(url, { history: "replace" });

// Replace the URL and state at the same time.
navigation.navigate(url, { history: "replace", state });

// You can still pass along info:
navigation.navigate(url, { history: "replace", state, info });
// Just like location.reload().

// Leave the state as-is, but pass some info.
navigation.reload({ info });

// Overwrite the state with a new value.
navigation.reload({ state, info });

These are just some of the capabilites of the API, please read the spec to know more about it, bleow are some of the examples I came across as I was reading the sepc

Don't forget to read the implementation plan.

Feel free to share this article. You may as well ping me on Twitter.