W3cubDocs

/Web APIs

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.

EventTarget Navigation

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. the currentEntry is not the first one in the history entry list), and false if it is not.

canGoForward Read only Experimental

Returns true if it is possible to navigate forwards in the navigation history (i.e. the currentEntry is not the last one in the history entry list), and false 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. Returns null 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.

navigate() Experimental

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 by key.

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.

navigate Experimental

Fired when any type of navigation is initiated, allowing you to intercept as required.

navigateerror Experimental

Fired when a navigation fails.

navigatesuccess Experimental

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;

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

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
Navigation 102 102 No No 88 No 102 102 No 70 No 19.0
back 102 102 No No 88 No 102 102 No 70 No 19.0
canGoBack 102 102 No No 88 No 102 102 No 70 No 19.0
canGoForward 102 102 No No 88 No 102 102 No 70 No 19.0
currentEntry 102 102 No No 88 No 102 102 No 70 No 19.0
currententrychange_event 102 102 No No 88 No 102 102 No 70 No 19.0
entries 102 102 No No 88 No 102 102 No 70 No 19.0
forward 102 102 No No 88 No 102 102 No 70 No 19.0
navigate 102 102 No No 88 No 102 102 No 70 No 19.0
navigate_event 102 102 No No 88 No 102 102 No 70 No 19.0
navigateerror_event 102 102 No No 88 No 102 102 No 70 No 19.0
navigatesuccess_event 102 102 No No 88 No 102 102 No 70 No 19.0
reload 102 102 No No 88 No 102 102 No 70 No 19.0
transition 102 102 No No 88 No 102 102 No 70 No 19.0
traverseTo 102 102 No No 88 No 102 102 No 70 No 19.0
updateCurrentEntry 102 102 No No 88 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/Navigation