W3cubDocs

/Web APIs

NavigateEvent

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The NavigateEvent interface of the Navigation API is the event object for the navigate event, which fires when any type of navigation is initiated (this includes usage of History API features like History.go()). NavigateEvent provides access to information about that navigation, and allows developers to intercept and control the navigation handling.

Event NavigateEvent

Constructor

NavigateEvent() Experimental

Creates a new NavigateEvent object instance.

Instance properties

Inherits properties from its parent, Event.

canIntercept Read only Experimental

Returns true if the navigation can be intercepted, or false otherwise (e.g. you can't intercept a cross-origin navigation).

destination Read only Experimental

Returns a NavigationDestination object representing the destination being navigated to.

downloadRequest Read only Experimental

Returns the filename of the file requested for download, in the case of a download navigation (e.g. an <a> or <area> element with a download attribute), or null otherwise.

formData Read only Experimental

Returns the FormData object representing the submitted data in the case of a POST form submission, or null otherwise.

hashChange Read only Experimental

Returns true if the navigation is a fragment navigation (i.e. to a fragment identifier in the same document), or false otherwise.

info Read only Experimental

Returns the info data value passed by the initiating navigation operation (e.g. Navigation.back(), or Navigation.navigate()), or undefined if no info data was passed.

navigationType Read only Experimental

Returns the type of the navigation — push, reload, replace, or traverse.

signal Read only Experimental

Returns an AbortSignal, which will become aborted if the navigation is cancelled (e.g. by the user pressing the browser's "Stop" button, or another navigation starting and thus cancelling the ongoing one).

userInitiated Read only Experimental

Returns true if the navigation was initiated by the user (e.g. by clicking a link, submitting a form, or pressing the browser's "Back"/"Forward" buttons), or false otherwise.

Instance methods

Inherits methods from its parent, Event.

intercept() Experimental

Intercepts this navigation, turning it into a same-document navigation to the destination URL. It can accept a handler function that defines what the navigation handling behavior should be, plus focusReset and scroll options to control behavior as desired.

scroll() Experimental

Can be called to manually trigger the browser-driven scrolling behavior that occurs in response to the navigation, if you want it to happen before the navigation handling has completed.

Examples

Handling a navigation using intercept()

js

navigation.addEventListener("navigate", (event) => {
  // Exit early if this navigation shouldn't be intercepted,
  // e.g. if the navigation is cross-origin, or a download request
  if (shouldNotIntercept(event)) return;

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

  if (url.pathname.startsWith("/articles/")) {
    event.intercept({
      async handler() {
        // The URL has already changed, so show a placeholder while
        //fetching the new content, such as a spinner or loading page
        renderArticlePagePlaceholder();

        // Fetch the new content and display when ready
        const articleContent = await getArticleContent(url.pathname);
        renderArticlePage(articleContent);
      },
    });
  }
});

Note: Before the Navigation API was available, to do something similar you'd have to listen for all click events on links, run e.preventDefault(), perform the appropriate History.pushState() call, then set up the page view based on the new URL. And this wouldn't handle all navigations — only user-initiated link clicks.

Handling scrolling using scroll()

In this example of intercepting a navigation, the handler() function starts by fetching and rendering some article content, but then fetches and renders some secondary content afterwards. It makes sense to scroll the page to the main article content as soon as it is available so the user can interact with it, rather than waiting until the secondary content is also rendered. To achieve this, we have added a scroll() call between the two.

js

navigation.addEventListener("navigate", (event) => {
  if (shouldNotIntercept(navigateEvent)) return;
  const url = new URL(event.destination.url);

  if (url.pathname.startsWith("/articles/")) {
    event.intercept({
      async handler() {
        const articleContent = await getArticleContent(url.pathname);
        renderArticlePage(articleContent);

        event.scroll();

        const secondaryContent = await getSecondaryContent(url.pathname);
        addSecondaryContent(secondaryContent);
      },
    });
  }
});

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
NavigateEvent 102 102 No No No No 102 102 No 70 No 19.0
NavigateEvent 102 102 No No No No 102 102 No 70 No 19.0
canIntercept 105 105 No No No No 105 105 No 72 No 20.0
canTransition 102–108 102–108 No No No No 102–108 102–108 No 70–73 No 19.0–21.0
destination 102 102 No No No No 102 102 No 70 No 19.0
downloadRequest 102 102 No No No No 102 102 No 70 No 19.0
formData 102 102 No No No No 102 102 No 70 No 19.0
hasUAVisualTransition 118 No No No No No 118 118 No No No No
hashChange 102 102 No No No No 102 102 No 70 No 19.0
info 102 102 No No No No 102 102 No 70 No 19.0
intercept 105 105 No No No No 105 105 No 72 No 20.0
navigationType 102 102 No No No No 102 102 No 70 No 19.0
restoreScroll 102–108 102–108 No No No No 102–108 102–108 No 70–73 No 19.0–21.0
scroll 105 105 No No No No 105 105 No 72 No 20.0
signal 102 102 No No No No 102 102 No 70 No 19.0
transitionWhile 102–108 102–108 No No No No 102–108 102–108 No 70–73 No 19.0–21.0
userInitiated 102 102 No No No No 102 102 No 70 No 19.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/NavigateEvent