Navigation API

[rd3k]

Description

The Navigation API was previously submitted for consideration in Interop 2023.

Since then it has matured, graduated from being a HTML Spec PR to a part of the spec and landed in Chrome 110 (~ February 7th 2023, plus other Chromium-based browsers since).

Please note that I do not represent an implementer. I am a web developer that is enthusiastic about this massive improvement over the History API.

Some excellent features include:

• The navigate event: a powerful way to conditionally convert cross-document navigations to same-document navigations
• entries: exposing a list of NavigationHistoryEntry as an abstraction over same-origin session history entries
• Focus reset and scroll behaviour
• Handling a 'traverse' navigation event is much more intuitive than a popstate. You can avoid reacting to it, derive whether the direction was forward or backwards by comparing entry index, and much more.

Specification

https://html.spec.whatwg.org/multipage/nav-history-apis.html#navigation-api

Open Issues

• Will the current transitionWhile() design of updating the URL/history entry immediately meet web developer needs? WICG/navigation-api#66
• Event property to access the element who triggered a navigation WICG/navigation-api#225

Tests

https://wpt.fyi/results/navigation-api

Current Implementations

• Blink
• Gecko
• WebKit

Standards Positions

• Navigation API mozilla/standards-positions#543
• Navigation API WebKit/standards-positions#34
• Blink Intent to Ship (April 2022)

Browser bug reports

• Blink implementation (closed)
• Gecko implementation (pending)
• Webkit implementation (pending)

Developer discussions

Various, including:

• Support the Navigation API vuejs/router#1415

Polls & Surveys

• Came 7th in Results of MDN APIs & JavaScript survey #246 after being selected by ~18% of participants
• (Has there been a survey since?)
• This issue has a relatively large amount of '👍' reactions

Existing Usage

No response

Workarounds

• virtualstate/navigation (partial) polyfill

Accessibility Impact

No response

Privacy Impact

• https://github.com/WICG/navigation-api/blob/main/security-privacy-questionnaire.md

Other

TAG design reviews:

• App history API w3ctag/design-reviews#605
• Navigation API (formerly app history API) w3ctag/design-reviews#717

MDN documentation

[foolip]

For survey data and web developer demand, in preliminary results from State of HTML 2023, Navigation API was a somewhat common response to the freeform question "Which existing HTML features or browser APIs are you unable to use because of browser differences or lack of support?"

[atscott]

Angular router package caretaker here. I've been following the development of the Navigation API for quite some time now and I feel that this is a huge step forward from the current set of APIs we have available to us. Just a few of the things that require custom implementations in the Angular router (and certainly other framework routers) that are more easily solved with the Navigation API:

• Being able to inspect the entries is extremely valuable for restoring history when the application configuration wants to reject a navigation. Currently, we have to leave "breadcrumbs" on the history.state and use this to calculate where to move back to if we want to reject a back button click and restore history. This is done in Angular and Vue and likely other framework Router implementations.
• The above breadcrumbs for determining navigation direction aren't exposed in the Angular Router's public API. Getting this information as an application developer would require accessing the private router state on history, duplicating the state breadcrumbs, or waiting for the framework to make those things public. With the navigation API, this was easy to do in an app by just adding a currententrychange listener and comparing entry indexes, which I did when creating a view transition demo for different animations on back traversals.
• Similar "breadcrumbs" are used for scroll position restoration. Scrolling in SPA routers in general is often done with a lot of custom code. A few examples of the custom scroll behavior of SPA routers: Angular, React, and Vue.
  The current history.scrollRestoration is a lot less capable than the navigation API's ability to imperatively call scroll after the router knows the page is fully rendered.
• The ability to intercept any navigation would be powerful. Currently, forgetting to use the RouterLink directive in Angular and just using a plain anchor tag <a href="/"... can't be handled as a SPA navigation but this could be intercepted with the Navigation API. In addition, the fact that history.pushState and history.replaceState are not observable makes these direct history navigations hidden from the framework Router.
• The ability to let the browser know a navigation is happening is not possible with the history API. Without the applications putting this directly in the UI, site visitors have no good indication of ongoing navigations. In addition, intercepting the navigate event and keeping it unresolved for the duration of the framework router's navigation opens up the possibility for canceling the navigation directly from the browser API. This isn't possible either for SPA routers today.

Those are just a few points off of the top of my head. I'm sure we'll come across a whole host of other items that have previously been difficult to achieve with the current set of APIs or otherwise not at all possible while we continue to experiment with the Navigation API in the router.

[loganvolkers]

Started some conversations:

• Tanstack Router: Support the Navigation API TanStack/router#821
• React Router: Support the Navigation API remix-run/react-router#11046

[wpt-interop]

Thank you for proposing Navigation API for inclusion in Interop 2024.

We wanted to let you know that this proposal was not selected to be part of Interop this year.

This is because we got many more proposals than we could include in this year's project. Note that individual vendors may nevertheless choose to advance work in this area during the forthcoming year. We would welcome this proposal being resubmitted again next year if necessary.

For an overview of our process, see proposal selection. Thank you again for contributing to Interop 2024!

Posted on behalf of the Interop team.

[ryanflorence]

Bummer, was looking forward to using this in React Router ASAP because the history API is rough for users and completely lacking for accessibility.

For survey data and web developer demand

It's also one of those features many web developers don't know they want because frameworks have abstracted the current capabilities with lots of caveats.

Hopefully can make it into 2025!

[ryantownsend]

@ryanflorence I believe this API is being worked on in WebKit already: WebKit/WebKit@eabae2c so just because it's not in Interop, doesn't mean we won't see it in 2024.

I mirror your viewpoint that this isn't many are even aware of to know how important it is – frameworks have been abstracting this away for years. Let's just hope WebKit land it this year! 🤞