Navigation

Instance properties

Inherits properties from its parent, EventTarget.

activation Read only

Returns a NavigationActivation object containing information about the most recent cross-document navigation, which "activated" this Document.

canGoBack Read only

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

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

Returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.

transition Read only

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()

Navigates backwards by one entry in the navigation history.

entries()

Returns an array of NavigationHistoryEntry objects representing all existing history entries.

forward()

Navigates forwards by one entry in the navigation history.

navigate()

Navigates to a specific URL, updating any provided state in the history entries list.

reload()

Reloads the current URL, updating any provided state in the history entries list.

traverseTo()

Navigates to a specific NavigationHistoryEntry identified by key.

updateCurrentEntry()

Updates the state of the currentEntry; used in cases where the state change will be independent from a navigation or reload.

Events

Inherits events from its parent, EventTarget.

currententrychange

Fired when the Navigation.currentEntry has changed.

navigate

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

navigateerror

Fired when a navigation fails.

navigatesuccess

Fired when a successful navigation has finished.

Examples

Moving forwards and backwards in the history

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

// 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

navigation.navigate(url, { state: newState });

Or

navigation.reload({ state: newState });

Or if the state is independent from a navigation or reload:

navigation.updateCurrentEntry({ state: newState });

Specifications

Browser compatibility

See also

• Modern client-side routing: the Navigation API
• Navigation API explainer
• Navigation API live demo (view demo source)