Navigation
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The Navigation
interface of the Navigation API allows control over all navigation actions for the current window
in one central place, including initiating navigations programmatically, examining navigation history entries, and managing navigations as they happen.
It is accessed via the Window.navigation
property.
The Navigation API only exposes history entries created in the current browsing context that have the same origin as the current page (e.g. not navigations inside embedded <iframe>
s, or cross-origin navigations), providing an accurate list of all previous history entries just for your app. This makes traversing the history a much less fragile proposition than with the older History API.
Instance properties
Inherits properties from its parent, EventTarget
.
canGoBack
Read only Experimental-
Returns
true
if it is possible to navigate backwards in the navigation history (i.e. thecurrentEntry
is not the first one in the history entry list), andfalse
if it is not. canGoForward
Read only Experimental-
Returns
true
if it is possible to navigate forwards in the navigation history (i.e. thecurrentEntry
is not the last one in the history entry list), andfalse
if it is not. currentEntry
Read only Experimental-
Returns a
NavigationHistoryEntry
object representing the location the user is currently navigated to right now. transition
Read only Experimental-
Returns a
NavigationTransition
object representing the status of an in-progress navigation, which can be used to track it. Returnsnull
if no navigation is currently in progress.
Instance methods
Inherits methods from its parent, EventTarget
.
back()
Experimental-
Navigates backwards by one entry in the navigation history.
entries()
Experimental-
Returns an array of
NavigationHistoryEntry
objects representing all existing history entries. forward()
Experimental-
Navigates forwards by one entry in the navigation history.
-
Navigates to a specific URL, updating any provided state in the history entries list.
reload()
Experimental-
Reloads the current URL, updating any provided state in the history entries list.
traverseTo()
Experimental-
Navigates to a specific
NavigationHistoryEntry
identified bykey
. updateCurrentEntry()
Experimental-
Updates the state of the
currentEntry
; used in cases where the state change will be independent from a navigation or reload.
Events
currententrychange
Experimental-
Fired when the
Navigation.currentEntry
has changed. -
Fired when any type of navigation is initiated, allowing you to intercept as required.
-
Fired when a navigation fails.
-
Fired when a successful navigation has finished.
Examples
Moving forwards and backwards in the history
js
async function backHandler() {
if (navigation.canGoBack) {
await navigation.back().finished;
// Handle any required clean-up after
// navigation has finished
} else {
displayBanner("You are on the first page");
}
}
async function forwardHandler() {
if (navigation.canGoForward) {
await navigation.forward().finished;
// Handle any required clean-up after
// navigation has finished
} else {
displayBanner("You are on the last page");
}
}
Traversing to a specific history entry
js
// 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;
Navigating and updating state
js
navigation.navigate(url, { state: newState });
Or
js
navigation.reload({ state: newState });
Or if the state is independent from a navigation or reload:
js
navigation.updateCurrentEntry({ state: newState });
Specifications
Specification |
---|
Unknown specification # global |
Browser compatibility
BCD tables only load in the browser