Standardizing client-side routing through a brand new API which completely overhauls building single-page applications.
 Sam Thorogood [X](https://twitter.com/samthor) [GitHub](https://github.com/samthor) [Homepage](https://whistlr.info/)  Jake Archibald [X](https://twitter.com/jaffathecake) [Homepage](https://jakearchibald.com/)
Browser Support
- ' d='M96 183a64 64 0 0 1-23-23L17 64a128 128 0 0 0 111 192l55-96a64 64 0 0 1-87 23Z'/%3E%3Cpath fill='url(%23b)' d='M192 128a64 64 0 0 1-9 32l-55 96A128 128 0 0 0 239 64H128a64 64 0 0 1 64 64Z'/%3E%3Ccircle cx='128' cy='128' r='52' fill='%231a73e8'/%3E%3Cpath fill='url(%23c)' d='M96 73a64 64 0 0 1 32-9h111a128 128 0 0 0-222 0l56 96a64 64 0 0 1 23-87Z'/%3E%3C/svg%3E)
- ' xlink:href='%23A'%3E%3Cstop offset='.76' stop-opacity='0'/%3E%3Cstop offset='.95' stop-opacity='.5'/%3E%3Cstop offset='1'/%3E%3C/radialGradient%3E%3CradialGradient id='F' cx='2523' cy='4680' r='20243' gradientTransform='matrix(-.03715 .99931 -2.12836 -.07913 13579 3530)' xlink:href='%23A'%3E%3Cstop offset='0' stop-color='%2335c1f1'/%3E%3Cstop offset='.11' stop-color='%2334c1ed'/%3E%3Cstop offset='.23' stop-color='%232fc2df'/%3E%3Cstop offset='.31' stop-color='%232bc3d2'/%3E%3Cstop offset='.67' stop-color='%2336c752'/%3E%3C/radialGradient%3E%3CradialGradient id='G' cx='24247' cy='7758' r='9734' gradientTransform='matrix(.28109 .95968 -.78353 .22949 24510 -16292)' xlink:href='%23A'%3E%3Cstop offset='0' stop-color='%2366eb6e'/%3E%3Cstop offset='1' stop-color='%2366eb6e' stop-opacity='0'/%3E%3C/radialGradient%3E%3Cpath id='H' d='M24105 20053a9345 9345 0 01-1053 472 10202 10202 0 01-3590 646c-4732 0-8855-3255-8855-7432 0-1175 680-2193 1643-2729-4280 180-5380 4640-5380 7253 0 7387 6810 8137 8276 8137 791 0 1984-230 2704-456l130-44a12834 12834 0 006660-5282c220-350-168-757-535-565z'/%3E%3Cpath id='I' d='M11571 25141a7913 7913 0 01-2273-2137 8145 8145 0 01-1514-4740 8093 8093 0 013093-6395 8082 8082 0 011373-859c312-148 846-414 1554-404a3236 3236 0 012569 1297 3184 3184 0 01636 1866c0-21 2446-7960-8005-7960-4390 0-8004 4166-8004 7820 0 2319 538 4170 1212 5604a12833 12833 0 007684 6757 12795 12795 0 003908 610c1414 0 2774-233 4045-656a7575 7575 0 01-6278-803z'/%3E%3Cpath id='J' d='M16231 15886c-80 105-330 250-330 566 0 260 170 512 472 723 1438 1003 4149 868 4156 868a5954 5954 0 003027-839 6147 6147 0 001133-850 6180 6180 0 001910-4437c26-2242-796-3732-1133-4392-2120-4141-6694-6525-11668-6525-7011 0-12703 5635-12798 12620 47-3654 3679-6605 7996-6605 350 0 2346 34 4200 1007 1634 858 2490 1894 3086 2921 618 1067 728 2415 728 2952s-271 1333-780 1990z'/%3E%3Cuse fill='url(%23B)' xlink:href='%23H'/%3E%3Cuse fill='url(%23D)' opacity='.35' xlink:href='%23H'/%3E%3Cuse fill='url(%23C)' xlink:href='%23I'/%3E%3Cuse fill='url(%23E)' opacity='.4' xlink:href='%23I'/%3E%3Cuse fill='url(%23F)' xlink:href='%23J'/%3E%3Cuse fill='url(%23G)' xlink:href='%23J'/%3E%3C/svg%3E)
- ' gradientUnits='userSpaceOnUse'%3E%3Cstop offset='.2' stop-color='%239059ff' stop-opacity='0'/%3E%3Cstop offset='.3' stop-color='%238c4ff3' stop-opacity='.1'/%3E%3Cstop offset='.8' stop-color='%237716a8' stop-opacity='.5'/%3E%3Cstop offset='1' stop-color='%236e008b' stop-opacity='.6'/%3E%3C/radialGradient%3E%3CradialGradient id='ff-g' cx='239.1' cy='34.6' r='171.6' gradientUnits='userSpaceOnUse'%3E%3Cstop offset='0' stop-color='%23ffe226'/%3E%3Cstop offset='.1' stop-color='%23ffdb27'/%3E%3Cstop offset='.3' stop-color='%23ffc82a'/%3E%3Cstop offset='.5' stop-color='%23ffa930'/%3E%3Cstop offset='.7' stop-color='%23ff7e37'/%3E%3Cstop offset='.8' stop-color='%23ff7139'/%3E%3C/radialGradient%3E%3CradialGradient id='ff-h' cx='374' cy='-74.3' r='732.2' gradientUnits='userSpaceOnUse'%3E%3Cstop offset='.1' stop-color='%23fff44f'/%3E%3Cstop offset='.5' stop-color='%23ff980e'/%3E%3Cstop offset='.6' stop-color='%23ff5634'/%3E%3Cstop offset='.7' stop-color='%23ff3647'/%3E%3Cstop offset='.9' stop-color='%23e31587'/%3E%3C/radialGradient%3E%3CradialGradient id='ff-i' cx='304.6' cy='7.1' r='536.4' gradientTransform='rotate(84 303 4)' gradientUnits='userSpaceOnUse'%3E%3Cstop offset='0' stop-color='%23fff44f'/%3E%3Cstop offset='.1' stop-color='%23ffe847'/%3E%3Cstop offset='.2' stop-color='%23ffc830'/%3E%3Cstop offset='.3' stop-color='%23ff980e'/%3E%3Cstop offset='.4' stop-color='%23ff8b16'/%3E%3Cstop offset='.5' stop-color='%23ff672a'/%3E%3Cstop offset='.6' stop-color='%23ff3647'/%3E%3Cstop offset='.7' stop-color='%23e31587'/%3E%3C/radialGradient%3E%3CradialGradient id='ff-j' cx='235' cy='98.1' r='457.1' gradientUnits='userSpaceOnUse'%3E%3Cstop offset='.1' stop-color='%23fff44f'/%3E%3Cstop offset='.5' stop-color='%23ff980e'/%3E%3Cstop offset='.6' stop-color='%23ff5634'/%3E%3Cstop offset='.7' stop-color='%23ff3647'/%3E%3Cstop offset='.9' stop-color='%23e31587'/%3E%3C/radialGradient%3E%3CradialGradient id='ff-k' cx='355.7' cy='124.9' r='500.3' gradientUnits='userSpaceOnUse'%3E%3Cstop offset='.1' stop-color='%23fff44f'/%3E%3Cstop offset='.2' stop-color='%23ffe141'/%3E%3Cstop offset='.5' stop-color='%23ffaf1e'/%3E%3Cstop offset='.6' stop-color='%23ff980e'/%3E%3C/radialGradient%3E%3ClinearGradient id='ff-a' x1='446.9' y1='76.8' x2='47.9' y2='461.8' gradientUnits='userSpaceOnUse'%3E%3Cstop offset='.1' stop-color='%23fff44f'/%3E%3Cstop offset='.1' stop-color='%23ffe847'/%3E%3Cstop offset='.2' stop-color='%23ffc830'/%3E%3Cstop offset='.4' stop-color='%23ff980e'/%3E%3Cstop offset='.4' stop-color='%23ff8b16'/%3E%3Cstop offset='.5' stop-color='%23ff672a'/%3E%3Cstop offset='.5' stop-color='%23ff3647'/%3E%3Cstop offset='.7' stop-color='%23e31587'/%3E%3C/linearGradient%3E%3ClinearGradient id='ff-l' x1='442.1' y1='74.8' x2='102.6' y2='414.3' gradientUnits='userSpaceOnUse'%3E%3Cstop offset='.2' stop-color='%23fff44f' stop-opacity='.8'/%3E%3Cstop offset='.3' stop-color='%23fff44f' stop-opacity='.6'/%3E%3Cstop offset='.5' stop-color='%23fff44f' stop-opacity='.2'/%3E%3Cstop offset='.6' stop-color='%23fff44f' stop-opacity='0'/%3E%3C/linearGradient%3E%3C/defs%3E%3Cpath d='M479 166c-11-25-32-52-49-60a249 249 0 0 1 25 73c-27-68-73-95-111-155a255 255 0 0 1-8-14 44 44 0 0 1-4-9 1 1 0 0 0 0-1 1 1 0 0 0-1 0c-60 35-81 101-83 134a120 120 0 0 0-66 25 71 71 0 0 0-6-5 111 111 0 0 1-1-58c-25 11-44 29-58 44-9-12-9-52-8-60l-8 4a175 175 0 0 0-24 21 210 210 0 0 0-22 26 203 203 0 0 0-32 73l-1 2-2 15a229 229 0 0 0-4 34v1a240 240 0 0 0 477 40l1-9c5-41 0-84-15-121zM202 355l3 1-3-1zm55-145zm198-31z' fill='url(%23ff-a)'/%3E%3Cpath d='M479 166c-11-25-32-52-49-60 14 26 22 53 25 72v1a207 207 0 0 1-206 279c-113-3-212-87-231-197-3-17 0-26 2-40-2 11-3 14-4 34v1a240 240 0 0 0 477 40l1-9c5-41 0-84-15-121z' fill='url(%23ff-b)'/%3E%3Cpath d='M479 166c-11-25-32-52-49-60 14 26 22 53 25 72v1a207 207 0 0 1-206 279c-113-3-212-87-231-197-3-17 0-26 2-40-2 11-3 14-4 34v1a240 240 0 0 0 477 40l1-9c5-41 0-84-15-121z' fill='url(%23ff-c)'/%3E%3Cpath d='m362 195 1 1a130 130 0 0 0-22-29C266 92 322 5 331 0c-60 35-81 101-83 134l9-1c45 0 84 25 105 62z' fill='url(%23ff-d)'/%3E%3Cpath d='M257 210c-1 6-22 26-29 26-68 0-80 41-80 41 3 35 28 64 57 79l4 2 7 3a107 107 0 0 0 31 6c120 6 143-143 57-186 22-4 45 5 58 14-21-37-60-62-105-62l-9 1a120 120 0 0 0-66 25l17 16c16 16 58 33 58 35z' fill='url(%23ff-e)'/%3E%3Cpath d='M257 210c-1 6-22 26-29 26-68 0-80 41-80 41 3 35 28 64 57 79l4 2 7 3a107 107 0 0 0 31 6c120 6 143-143 57-186 22-4 45 5 58 14-21-37-60-62-105-62l-9 1a120 120 0 0 0-66 25l17 16c16 16 58 33 58 35z' fill='url(%23ff-f)'/%3E%3Cpath d='m171 151 5 3a111 111 0 0 1-1-58c-25 11-44 29-58 44 1 0 36 0 54 11z' fill='url(%23ff-g)'/%3E%3Cpath d='M18 261a242 242 0 0 0 231 197 207 207 0 0 0 206-279c8 56-20 110-64 146-86 71-169 43-186 31l-3-1c-50-24-71-70-67-110-42 0-57-35-57-35s38-28 89-4c46 22 90 4 90 4 0-2-42-19-58-35l-17-16a71 71 0 0 0-6-5l-5-3c-18-11-52-11-54-11-9-12-9-51-8-60l-8 4a175 175 0 0 0-24 21 210 210 0 0 0-22 26 203 203 0 0 0-32 73c0 1-9 38-5 57z' fill='url(%23ff-h)'/%3E%3Cpath d='M341 167a130 130 0 0 1 22 29 46 46 0 0 1 4 3c55 50 26 121 24 126 44-36 72-90 64-146-27-68-73-95-111-155a255 255 0 0 1-8-14 44 44 0 0 1-4-9 1 1 0 0 0 0-1 1 1 0 0 0-1 0c-9 5-65 92 10 167z' fill='url(%23ff-i)'/%3E%3Cpath d='M367 199a46 46 0 0 0-4-3l-1-1c-13-9-36-18-58-15 86 44 63 193-57 187a107 107 0 0 1-31-6 131 131 0 0 1-11-5c17 12 99 39 186-31 2-5 31-76-24-126z' fill='url(%23ff-j)'/%3E%3Cpath d='M148 277s12-41 80-41c7 0 28-20 29-26s-44 18-90-4c-51-24-89 4-89 4s15 35 57 35c-4 40 16 85 67 110l3 1c-29-15-54-44-57-79z' fill='url(%23ff-k)'/%3E%3Cpath d='M479 166c-11-25-32-52-49-60a249 249 0 0 1 25 73c-27-68-73-95-111-155a255 255 0 0 1-8-14 44 44 0 0 1-4-9 1 1 0 0 0 0-1 1 1 0 0 0-1 0c-60 35-81 101-83 134l9-1c45 0 84 25 105 62-13-9-36-18-58-14 86 43 63 192-57 186a107 107 0 0 1-31-6 131 131 0 0 1-11-5l-3-1 3 1c-29-15-54-44-57-79 0 0 12-41 80-41 7 0 28-20 29-26 0-2-42-19-58-35l-17-16a71 71 0 0 0-6-5 111 111 0 0 1-1-58c-25 11-44 29-58 44-9-12-9-52-8-60l-8 4a175 175 0 0 0-24 21 210 210 0 0 0-22 26 203 203 0 0 0-32 73l-1 2-2 15a279 279 0 0 0-4 34v1a240 240 0 0 0 477 40l1-9c5-41 0-84-15-121zm-24 13z' fill='url(%23ff-l)'/%3E%3C/svg%3E)
- ' xlink:href='%23s-b'%3E%3Cstop offset='0' stop-color='%2324a5f3' stop-opacity='0' /%3E%3Cstop offset='1' stop-color='%231e8ceb' /%3E%3C/radialGradient%3E%3CradialGradient id='s-j' cx='109.3' cy='13.8' r='93.1' gradientTransform='matrix(-.02 1.1 -1.04 -.02 137 -115)' xlink:href='%23s-b'%3E%3Cstop offset='0' stop-opacity='0' /%3E%3Cstop offset='1' stop-color='%235488d6' stop-opacity='0' /%3E%3Cstop offset='1' stop-color='%235d96eb' /%3E%3C/radialGradient%3E%3C/defs%3E%3Crect width='220' height='220' x='22' y='-107' fill='url(%23s-a)' ry='49' transform='matrix(.57 0 0 .57 187 256)' /%3E%3Cg transform='translate(194 190)'%3E%3Ccircle cx='67.8' cy='67.7' fill='url(%23s-c)' paint-order='stroke fill markers' r='54' /%3E%3Ccircle cx='-69.9' cy='69.3' fill='url(%23s-i)' transform='translate(138 -2)' r='54' /%3E%3C/g%3E%3Cellipse cx='120' cy='14.2' fill='url(%23s-j)' rx='93.1' ry='93.7' transform='matrix(.58 0 0 .58 192 250)' /%3E%3Cg transform='matrix(.58 0 0 .57 197 182)'%3E%3Cpath fill='%23cac7c8' d='M46 192h1l72-48-7-9-66 57Z' /%3E%3Cpath fill='%23fbfffc' d='M46 191v1l66-57-7-9-59 65Z' /%3E%3Cpath fill='url(%23s-d)' d='m119 144-7-9 66-57-59 66Z' /%3E%3Cpath fill='%23fb645c' d='m105 126 7 9 66-57-1-1-72 49Z' /%3E%3C/g%3E%3Cpath stroke='%23fff' stroke-linecap='round' stroke-miterlimit='1' stroke-width='1.3' d='m287 278 3-2m-12-17 8-2m-8-3h4m-4-13 8 2m-8 3h4m-1-13 7 3m-4-11 7 4m-2-11 6 6m0-12 6 7m1-11 4 6m4-10 3 7m5-9 2 7m15-7-1 7m10-5-3 7m11-4-4 7m11-2-5 6m16 7-7 4m10 4-7 3m10 6-8 1m8 16-8-2m5 10-7-3m4 11-7-4m2 11-6-5m0 11-5-6m-2 11-4-7m-4 11-3-8m-6 10-1-8m-16 8 2-8m-10 5 3-7m-11 4 4-7m-11 2 5-6m-8 3 3-3m4 8 2-3m5 8 2-4m6 7 1-4m8 5v-4m8 4v-4m9 3-1-4m9 1-2-4m9 0-2-4m9-2-3-3m8-4-3-2m8-5-4-2m7-6-4-1m5-8h-4m4-8h-4m3-9-4 1m1-9-4 2m-1-9-3 2m-2-9-3 3m-4-8-2 3m-5-8-2 4m-6-6-1 3m-8-5v4m-8-4v4m-9-2 1 3m-9 0 2 3m-9 1 2 3m-9 2 3 3m-8 4 3 2m-8 5 4 2m-7 6 4 1m-4 25 4-1m-2 5 7-3m-6 7 4-2m-2 6 7-4m-13-21h8m41-41v-8m0 99v-8m49-42h-8' transform='translate(-65 8)' /%3E%3C/svg%3E)
[Source](https://developer.mozilla.org/docs/Web/API/Navigation)
> [!NOTE]
> **Note:** This API was known as the "App History API" during development, but has since been renamed to the "Navigation API".
Single-page applications, or SPAs, are defined by a core feature: dynamically rewriting their content as the user interacts with the site, instead of the default method of loading entirely new pages from the server.
While SPAs have been able to bring you this feature via the History API (or in limited cases, by adjusting the site's #hash part), it's a [clunky API](https://html5doctor.com/interview-with-ian-hickson-html-editor/#:%7E:text=My%20biggest%20mistake%E2%80%A6there%20are%20so%20many%20to%20choose%20from!%20pushState()%20is%20my%20favourite%20mistake) developed long-before SPAs were the norm---and the web is crying out for a completely new approach.
The Navigation API is a proposed API that completely overhauls this space, rather than trying to simply patch History API's rough edges.
(For example, [Scroll Restoration](https://developer.chrome.com/blog/history-api-scroll-restoration) patched the History API rather than trying to reinvent it.)
> [!NOTE]
> **Note:** The Navigation API launched in Chrome 102. Check out [our demo](https://gigantic-honored-octagon.glitch.me/).
This post describes the Navigation API at a high level.
To read the technical proposal, see the
[Draft Report in the WICG repository](https://wicg.github.io/navigation-api/).
## Example usage
To use the Navigation API, start by adding a `"navigate"` listener on the global `navigation` object.
This event is fundamentally *centralized*: it will fire for all types of navigations, whether the user performed an action (such as clicking a link, submitting a form, or going back and forward) or when navigation is triggered programmatically (i.e., via your site's code).
In most cases, it lets your code override the browser's default behavior for that action.
For SPAs, that likely means keeping the user on the same page and loading or changing the site's content.
A `NavigateEvent` is passed to the `"navigate"` listener which contains information about the navigation, such as the destination URL, and allows you to respond to the navigation in one centralized place.
A basic `"navigate"` listener could look like this:
navigation.addEventListener('navigate', navigateEvent => {
// Exit early if this navigation shouldn't be intercepted.
// The properties to look at are discussed later in the article.
if (shouldNotIntercept(navigateEvent)) return;
const url = new URL(navigateEvent.destination.url);
if (url.pathname === '/') {
navigateEvent.intercept({handler: loadIndexPage});
} else if (url.pathname === '/cats/') {
navigateEvent.intercept({handler: loadCatsPage});
}
});
You can deal with the navigation in one of two ways:
- Calling `intercept({ handler })` (as described above) to handle the navigation.
- Calling `preventDefault()`, which can cancel the navigation completely.
> [!NOTE]
> **Note:** An earlier version of this API used `navigateEvent.transitionWhile(promise)` rather than `navigateEvent.intercept({ handler })`. `intercept` is available from Chrome 105. `transitionWhile` is deprecated, and will be removed in Chrome 108.
This example calls `intercept()` on the event.
The browser calls your `handler` callback, which should configure the next state of your site.
This will create a transition object, `navigation.transition`, which other code can use to track the progress of the navigation.
> [!IMPORTANT]
> **Key term:** In this context 'transition' refers to the transition between one history entry and another. It isn't related to transition animations.
Both `intercept()` and `preventDefault()` are usually allowed, but have cases where they're unable to be called.
You can't handle navigations via `intercept()` if the navigation is a cross-origin navigation.
And you can't cancel a navigation via `preventDefault()` if the user is pressing the Back or Forward buttons in their browser; you should not be able to trap your users on your site.
(This is [being discussed on GitHub](https://github.com/WICG/navigation-api/issues/32).)
Even if you can't stop or intercept the navigation itself, the `"navigate"` event will still fire.
It's *informative*, so your code could, for example, log an Analytics event to indicate that a user is leaving your site.
## Why add another event to the platform?
A `"navigate"` event listener centralizes handling URL changes inside an SPA.
This is a difficult proposition using older APIs.
If you've ever written the routing for your own SPA using the History API, you might have added code like this:
function updatePage(event) {
event.preventDefault(); // we're handling this link
window.history.pushState(null, '', event.target.href);
// TODO: set up page based on new URL
}
const links = [...document.querySelectorAll('a[href]')];
links.forEach(link => link.addEventListener('click', updatePage));
This is fine, but not exhaustive.
Links might come and go on your page, and they're not the only way users can navigate through pages.
E.g., they may submit a form or even use an [image map](https://developer.mozilla.org/docs/Web/HTML/Element/map).
Your page might deal with these, but there's a long tail of possibilities which could just be simplified---something that the new Navigation API achieves.
Additionally, the above doesn't handle back/forward navigation. There's another event for that, `"popstate"`.
Personally, the History API often *feels* like it could go some way to help with these possibilities.
However, it really only has two surface areas: responding if the user presses Back or Forward in their browser, plus pushing and replacing URLs.
It doesn't have an analogy to `"navigate"`, except if you manually set up listeners for click events for example, as demonstrated above.
## Deciding how to handle a navigation
The `navigateEvent` contains a lot of information about the navigation that you can use to decide how to deal with a particular navigation.
The key properties are:
`canIntercept`
: If this is false, you can't intercept the navigation.
Cross-origin navigations and cross-document traversals cannot be intercepted.
`destination.url`
: Probably the most important piece of information to consider when handling the navigation.
`hashChange`
: True if the navigation is same-document, and the hash is the only part of the URL that's different to the current URL.
In modern SPAs, the hash should be for linking to different parts of the current document. So, if `hashChange` is true, you probably don't need to intercept this navigation.
`downloadRequest`
: If this is true, the navigation was initiated by a link with a `download` attribute.
In most cases, you don't need to intercept this.
`formData`
: If this isn't null, then this navigation is part of a POST form submission.
Make sure you take this into account when handling the navigation.
If you only want to handle GET navigations, avoid intercepting navigations where `formData` is not null.
See the example on handling [form submissions](https://developer.chrome.com/docs/web-platform/navigation-api#form-submissions) later in the article.
`navigationType`
: This is one of `"reload"`, `"push"`, `"replace"`, or `"traverse"`.
If it's `"traverse"`, then this navigation cannot be cancelled via `preventDefault()`.
For example, the `shouldNotIntercept` function used in the first example could be something like this:
function shouldNotIntercept(navigationEvent) {
return (
!navigationEvent.canIntercept ||
// If this is just a hashChange,
// just let the browser handle scrolling to the content.
navigationEvent.hashChange ||
// If this is a download,
// let the browser perform the download.
navigationEvent.downloadRequest ||
// If this is a form submission,
// let that go to the server.
navigationEvent.formData
);
}
## Intercepting
When your code calls `intercept({ handler })` from within its `"navigate"` listener, it informs the browser that it's now preparing the page for the new, updated state, and that the navigation may take some time.
The browser begins by capturing the scroll position for the current state, so it can be optionally restored later, then it calls your `handler` callback.
If your `handler` returns a promise (which happens automatically with [async functions](https://web.dev/articles/async-functions)), that promise tells the browser how long the navigation takes, and whether it's successful.
navigation.addEventListener('navigate', navigateEvent => {
if (shouldNotIntercept(navigateEvent)) return;
const url = new URL(navigateEvent.destination.url);
if (url.pathname.startsWith('/articles/')) {
navigateEvent.intercept({
async handler() {
const articleContent = await getArticleContent(url.pathname);
renderArticlePage(articleContent);
},
});
}
});
As such, this API introduces a semantic concept that the browser understands: an SPA navigation is currently occurring, over time, changing the document from a previous URL and state to a new one.
This has a number of potential benefits, including accessibility: browsers can surface the beginning, end, or potential failure of a navigation.
Chrome, for example, activates its native loading indicator, and allows the user to interact with the stop button. (This doesn't currently happen when the user navigates via the back/forward buttons, but that [will be fixed soon](https://bugs.chromium.org/p/chromium/issues/detail?id=1241202).)
### Navigation committing
When intercepting navigations, the new URL will take effect just before your `handler` callback is called.
If you don't update the DOM immediately, this creates a period where the old content is displayed along with the new URL.
This impacts things like relative URL resolution when fetching data or loading new subresources.
A way to delay the URL change is being [discussed on GitHub](https://github.com/WICG/navigation-api/issues/66), but it's generally recommended to immediately update the page with some sort of placeholder for the incoming content:
navigation.addEventListener('navigate', navigateEvent => {
if (shouldNotIntercept(navigateEvent)) return;
const url = new URL(navigateEvent.destination.url);
if (url.pathname.startsWith('/articles/')) {
navigateEvent.intercept({
async handler() {
// The URL has already changed, so quickly show a placeholder.
renderArticlePagePlaceholder();
// Then fetch the real data.
const articleContent = await getArticleContent(url.pathname);
renderArticlePage(articleContent);
},
});
}
});
This not only avoids URL resolution issues, it also feels fast because you're instantly responding to the user.
### Abort signals
Since you're able to do asynchronous work in an `intercept()` handler, it's possible for the navigation to become redundant.
This happens when:
- The user clicks another link, or some code performs another navigation. In this case the old navigation is abandoned in favour of the new navigation.
- The user clicks the 'stop' button in the browser.
To deal with any of these possibilities, the event passed to the `"navigate"` listener contains a `signal` property, which is an `AbortSignal`.
For more information see [Abortable fetch](https://developer.chrome.com/blog/abortable-fetch).
The short version is it basically provides an object that fires an event when you should stop your work.
Notably, you can pass an `AbortSignal` to any calls you make to `fetch()`, which will cancel in-flight network requests if the navigation is preempted.
This will both save the user's bandwidth, and reject the `Promise` returned by `fetch()`, preventing any following code from actions such as updating the DOM to show a now invalid page navigation.
Here's the previous example, but with `getArticleContent` inlined, showing how the `AbortSignal` can be used with `fetch()`:
navigation.addEventListener('navigate', navigateEvent => {
if (shouldNotIntercept(navigateEvent)) return;
const url = new URL(navigateEvent.destination.url);
if (url.pathname.startsWith('/articles/')) {
navigateEvent.intercept({
async handler() {
// The URL has already changed, so quickly show a placeholder.
renderArticlePagePlaceholder();
// Then fetch the real data.
const articleContentURL = new URL(
'/get-article-content',
location.href
);
articleContentURL.searchParams.set('path', url.pathname);
const response = await fetch(articleContentURL, {
signal: navigateEvent.signal,
});
const articleContent = await response.json();
renderArticlePage(articleContent);
},
});
}
});
### Scroll handling
When you `intercept()` a navigation, the browser will attempt to handle scrolling automatically.
For navigations to a new history entry (when `navigationEvent.navigationType` is `"push"` or `"replace"`), this means attempting to scroll to the part indicated by the URL fragment (the bit after the `#`), or resetting the scroll to the top of the page.
For reloads and traversals, this means restoring the scroll position to where it was last time this history entry was displayed.
By default, this happens once the promise returned by your `handler` resolves, but if it makes sense to scroll earlier, you can call `navigateEvent.scroll()`:
navigation.addEventListener('navigate', navigateEvent => {
if (shouldNotIntercept(navigateEvent)) return;
const url = new URL(navigateEvent.destination.url);
if (url.pathname.startsWith('/articles/')) {
navigateEvent.intercept({
async handler() {
const articleContent = await getArticleContent(url.pathname);
renderArticlePage(articleContent);
navigateEvent.scroll();
const secondaryContent = await getSecondaryContent(url.pathname);
addSecondaryContent(secondaryContent);
},
});
}
});
> [!NOTE]
> **Note:** Although `scroll()` looks like a single call, the browser may try to set the scroll position multiple times asynchronously. The means the browser can still scroll to the correct place, even if the content arrives slightly later, or moves around due to layout shifting.
Alternatively, you can opt out of automatic scroll handling entirely by setting the `scroll` option of `intercept()` to `"manual"`:
navigateEvent.intercept({
scroll: 'manual',
async handler() {
// ...
},
});
### Focus handling
Once the promise returned by your `handler` resolves, the browser will focus the first element with the [`autofocus` attribute](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/autofocus) set, or the `` element if no element has that attribute.
You can opt out of this behavior by setting the `focusReset` option of `intercept()` to `"manual"`:
navigateEvent.intercept({
focusReset: 'manual',
async handler() {
// ...
},
});
### Success and failure events
When your `intercept()` handler is called, one of two things will happen:
- If the returned `Promise` fulfills (or you did not call `intercept()`), the Navigation API will fire `"navigatesuccess"` with an `Event`.
- If the returned `Promise` rejects, the API will fire `"navigateerror"` with an `ErrorEvent`.
These events allow your code to deal with success or failure in a centralized way.
For example, you might deal with success by hiding a previously displayed progress indicator, like this:
navigation.addEventListener('navigatesuccess', event => {
loadingIndicator.hidden = true;
});
Or you might show an error message on failure:
navigation.addEventListener('navigateerror', event => {
loadingIndicator.hidden = true; // also hide indicator
showMessage(`Failed to load page: ${event.message}`);
});
The `"navigateerror"` event listener, which receives an `ErrorEvent`, is particularly handy as it's guaranteed to receive any errors from your code that's setting up a new page.
You can simply `await fetch()` knowing that if the network is unavailable, the error will eventually be routed to `"navigateerror"`.
## Navigation entries
`navigation.currentEntry` provides access to the current entry.
This is an object which describes where the user is right now.
This entry includes the current URL, metadata that can be used to identify this entry over time, and developer-provided state.
> [!NOTE]
> **Note:** Even sites that do not explicitly use the Navigation API will have a "current entry", and the entry is even updated or replaced if you use the older methods in the History API, `history.pushState()` and `history.replaceState()`, respectively.
The metadata includes `key`, a unique string property of each entry which represents the current entry and its *slot* .
This key remains the same even if the current entry's URL or state changes.
It's still in the same slot.
Conversely, if a user presses Back and then re-opens the same page, `key` will change as this new entry creates a new slot.
To a developer, `key` is useful because the Navigation API allows you to directly navigate the user to an entry with a matching key.
You're able to hold onto it, even in the states of other entries, in order to easily jump between pages.
// On JS startup, get the key of the first loaded page
// so the user can always go back there.
const {key} = navigation.currentEntry;
backToHomeButton.onclick = () => navigation.traverseTo(key);
// Navigate away, but the button will always work.
await navigation.navigate('/another_url').finished;
### State
The Navigation API surfaces a notion of "state", which is developer-provided information that is stored persistently on the current history entry, but which isn't directly visible to the user.
This is extremely similar to, but improved from, `history.state` in the History API.
In the Navigation API, you can call the `.getState()` method of the current entry (or any entry) to return a copy of its state:
console.log(navigation.currentEntry.getState());
By default, this will be `undefined`.
#### Setting state
Although state objects can be mutated, those changes are not saved back with the history entry, so:
const state = navigation.currentEntry.getState();
console.log(state.count); // 1
state.count++;
console.log(state.count); // 2
// But:
console.info(navigation.currentEntry.getState().count); // will still be 1
The correct way to set state is during script navigation:
navigation.navigate(url, {state: newState});
// Or:
navigation.reload({state: newState});
Where `newState` can be any [clonable object](https://developer.mozilla.org/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types).
If you want to update the state of the current entry, it's best to perform a navigation that replaces the current entry:
navigation.navigate(location.href, {state: newState, history: 'replace'});
Then, your `"navigate"` event listener can pick up this change via `navigateEvent.destination`:
navigation.addEventListener('navigate', navigateEvent => {
console.log(navigateEvent.destination.getState());
});
#### Updating state synchronously
Generally, it's better to update state asynchronously via `navigation.reload({state: newState})`, then your `"navigate"` listener can apply that state. However, sometimes the state change has already fully applied by the time your code hears about it, such as when the user toggles a `` element, or the user changes the state of a form input. In these cases, you may want to update state so these changes are preserved through reloads and traversals. This is possible using `updateCurrentEntry()`:
navigation.updateCurrentEntry({state: newState});
There's also an event to hear about this change:
navigation.addEventListener('currententrychange', () => {
console.log(navigation.currentEntry.getState());
});
But, if you find yourself reacting to state changes in `"currententrychange"`, you may be splitting or even duplicating your state-handing code between the `"navigate"` event and the `"currententrychange"` event, whereas `navigation.reload({state: newState})` would let you handle it in one place.
#### State vs URL params
Because state can be a structured object, it's tempting to use it for all your application state.
However, in many cases it's better to store that state in the URL.
If you would expect the state to be retained when the user shares the URL with another user, store it in the URL.
Otherwise, the state object is the better option.
### Access all entries
The "current entry" is not all, though.
The API also provides a way to access the entire list of entries that a user has navigated through while using your site via its `navigation.entries()` call, which returns a snapshot array of entries.
This could be used to, e.g., show a different UI based on how the user navigated to a certain page, or just to look back at the previous URLs or their states.
This is impossible with the current History API.
You can also listen for a `"dispose"` event on individual `NavigationHistoryEntry`s, which is fired when the entry is no longer part of browser history. This can happen as part of general cleanup, but also happen when navigating. For example, if you traverse back 10 places, then navigate forwards, those 10 history entries will be disposed.
## Examples
The `"navigate"` event fires for all types of navigation, as mentioned above.
(There's actually a [long appendix in the spec](https://github.com/WICG/navigation-api#appendix-types-of-navigations) of all possible types.)
While for many sites the most common case will be when the user clicks a ``, there are two notable, more complex navigation types that are worth covering.
### Programmatic navigation
First is programmatic navigation, where navigation is caused by a method call inside your client-side code.
You can call `navigation.navigate('/another_page')` from anywhere in your code to cause a navigation.
This will be handled by the centralized event listener registered on the `"navigate"` listener, and your centralized listener will be called synchronously.
This is intended as an improved aggregation of older methods like `location.assign()` and friends, plus the History API's methods `pushState()` and `replaceState()`.
> [!NOTE]
> **Note:** These older programmatic methods for changing the URL are all still supported with the Navigation API and now fire the` "navigate"` listener. That is, they're also handled centrally. Their signatures aren't modified in any way (i.e., they won't now return a `Promise`) by this new specification, and we imagine that in an older codebase, they'll be replaced by calls to `.navigate()` over time.
The `navigation.navigate()` method returns a object which contains two `Promise` instances in `{ committed, finished }`.
This allows the invoker can wait until either the transition is "committed" (the visible URL has changed and a new `NavigationHistoryEntry` is available) or "finished" (all promises returned by `intercept({ handler })` are complete---or rejected, due to failure or being preempted by another navigation).
The `navigate` method also has an options object, where you can set:
- `state`: the state for the new history entry, as available via the `.getState()` method on the `NavigationHistoryEntry`.
- `history`: which can be set to `"replace"` to replace the current history entry.
- `info`: an object to pass to the navigate event via `navigateEvent.info`.
In particular, `info` could be useful to, for example, denote a particular animation that causes the next page to appear.
(The alternative might be to set a global variable or include it as part of the #hash. Both options are a bit awkward.)
Notably, this `info` won't be replayed if a user later causes navigation, e.g., via their Back and Forward buttons.
In fact, it will always be `undefined` in those cases.
[Demo of opening from left or right](https://chief-low-specialist.glitch.me/)
`navigation` also has a number of other navigation methods, all which return an object containing `{ committed, finished }`.
I've already mentioned `traverseTo()` (which accepts a `key` that denotes a specific entry in the user's history) and `navigate()`.
It also includes `back()`, `forward()` and `reload()`.
These methods are all handled---just like `navigate()`---by the centralized `"navigate"` event listener.
### Form Submissions
Secondly, HTML `