Browser Navigation API: How to Handle Back and Forward Navigation in a Single-Page App

This ensures that directly opening /products renders the products view rather than always displaying the home page.

The server must also be configured to serve the application entry document for routes intended to be handled by the SPA. Otherwise, directly opening a nested route may result in a server-side 404 before the JavaScript application starts.

Handling Back and Forward Navigation

One of the main advantages of the Navigation API is that client-side navigation and browser history can be handled through a more consistent interface.

When a user clicks a link and the application intercepts the navigation, the browser can maintain the corresponding history entry. When the user later presses Back or Forward, the browser initiates navigation to another entry.

The application should render the destination associated with that navigation instead of assuming that every navigation is a new link click.

Example: Navigating Between Pages

Suppose a user follows this sequence:

Home → Products → About

The browser's history contains the navigation entries created by these transitions.

When the user presses Back, the browser returns to the Products entry. Pressing Back again returns to Home. Pressing Forward returns to Products.

The application should use the destination URL for rendering, rather than maintaining a separate history stack that can become inconsistent with the browser's history.

The Navigation API can also expose entry state through navigation.currentEntry. This is useful when an application needs to associate lightweight state with a history entry.

For example, an application may preserve a selected tab or a scroll position. That state should be designed carefully so that restoring a history entry produces the expected interface.

Avoid Creating Duplicate History Entries

Not every URL change should create a new history entry.

Use a new navigation entry when the user moves to a distinct view that should be revisited with the Back button. Use replacement behavior when correcting or replacing the current entry is more appropriate.

Unnecessary entries can make navigation frustrating. For example, if the application creates a new entry for every minor filter adjustment, the Back button may require many presses before returning to the previous page.

Choose history behavior based on the meaning of each user action.

Loading Data During Navigation

Real applications often need to fetch data when the route changes. For example, /products/101 may require an API request before the product details can be displayed.

The Navigation API's interception handler can perform asynchronous work:

navigation.addEventListener("navigate", (event) => {
  if (!event.canIntercept) {
    return;
  }

  if (!event.destination.url.startsWith(location.origin)) {
    return;
  }

  const destination = new URL(event.destination.url);

  if (destination.pathname !== "/products") {
    return;
  }

  event.intercept({
    handler: async () => {
      app.innerHTML = "<p>Loading products...</p>";

      try {
        const response = await fetch("/api/products");

        if (!response.ok) {
          throw new Error(
            `Request failed: ${response.status}`
          );
        }

        const products = await response.json();

        const list = document.createElement("ul");

        for (const product of products) {
          const item = document.createElement("li");
          item.textContent = product.name;
          list.appendChild(item);
        }

        app.replaceChildren(
          Object.assign(document.createElement("h1"), {
            textContent: "Products"
          }),
          list
        );
      } catch (error) {
        app.textContent = "Unable to load products.";
        console.error(error);
      }
    }
  });
});

This example demonstrates asynchronous data loading and safe text rendering. It assumes that the API returns an array of objects containing a name property.

The handler checks the HTTP response before processing the returned JSON. This prevents unsuccessful HTTP responses from being treated as successful product data.

For a production application, the router should also coordinate concurrent navigations, loading indicators, cancellation, and stale requests. If a user navigates away while a request is running, the application should avoid allowing the old request to overwrite the newly selected page.

Navigation API vs. History API

The History API remains useful and is supported across a broad range of browsers. The Navigation API provides a more integrated approach to navigation handling in supporting browsers.

The Navigation API can reduce the amount of custom routing infrastructure an application needs, but it does not automatically replace established routing libraries. Frameworks may already provide route matching, nested layouts, data loading, error boundaries, and compatibility handling.

Choose the approach that best fits the application's architecture and browser support requirements.

Best Practices

Preserve Standard Links

Use real links with valid href values. This supports expected browser behavior and gives the server a route to handle when client-side navigation is unavailable.

Keep the URL and UI Synchronized

Render the route associated with the current URL. Avoid maintaining an independent navigation stack that can diverge from the browser's history.

Handle Errors During Navigation

Data requests can fail because of network problems, server errors, or invalid responses. Provide a useful error view rather than leaving the application in a permanent loading state.

Avoid Unnecessary Interception

Allow downloads, external links, and navigations that require a full document load to follow their normal browser behavior.

Test Direct Navigation

Open nested routes directly in the address bar, refresh them, and test Back and Forward navigation. Confirm that the server and client agree on how routes are handled.

Check Browser Support

Feature-detect the Navigation API before using it. If the application supports browsers without it, provide a History API fallback or use a routing library that already handles compatibility.

Common Mistakes to Avoid

Advantages and Disadvantages

Advantages

• Provides a unified interface for observing and handling navigation.

• Supports client-side navigation without requiring a full document reload for eligible transitions.

• Exposes navigation-entry information that can help manage history state.

• Can reduce the amount of custom event handling needed in an SPA.

• Works with ordinary links when the application is designed to preserve standard browser behavior.

Disadvantages

• Browser support must be considered.

• Applications still need route matching, rendering, and data-loading logic.

• Navigation interception can become complex when downloads, external URLs, and nested routes are involved.

• Existing frameworks may already provide routing features that make a custom implementation unnecessary.

Summary

The Browser Navigation API provides a more integrated way to manage navigation in single-page applications. It allows applications to observe navigation requests, intercept eligible transitions, and work with browser navigation entries.

To use it effectively, render the initial URL, intercept only the navigations the application intends to handle, and keep the visible interface synchronized with browser history. When routes require asynchronous data, handle errors and prevent outdated requests from replacing newer content.

The Navigation API is useful for custom routers, but it does not eliminate the need for sound routing design. Preserve standard links, test Back and Forward behavior, and provide a fallback when supporting browsers that do not implement the API.