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.
Constructor
-
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, orfalse
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 adownload
attribute), ornull
otherwise. formData
Read only Experimental-
Returns the
FormData
object representing the submitted data in the case of aPOST
form submission, ornull
otherwise. hashChange
Read only Experimental-
Returns
true
if the navigation is a fragment navigation (i.e. to a fragment identifier in the same document), orfalse
otherwise. info
Read only Experimental-
Returns the
info
data value passed by the initiating navigation operation (e.g.Navigation.back()
, orNavigation.navigate()
), orundefined
if noinfo
data was passed. -
Returns the type of the navigation —
push
,reload
,replace
, ortraverse
. 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), orfalse
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, plusfocusReset
andscroll
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
Specification |
---|
Unknown specification # navigate-event-class |
Browser compatibility
BCD tables only load in the browser