Navigation: navigate() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The navigate()
method of the
Navigation
interface navigates to a specific URL, updating any provided state in the history entries list.
Syntax
js
navigate(url)
navigate(url, options)
Parameters
url
-
The destination URL to navigate to. Note that when calling
navigate()
on a another window'snavigation
object, the URL will be resolved relative to the target window's URL, not the calling window's URL. This matches the behavior of the History API, but not the behavior of the Location API. options
Optional-
An options object containing the following properties:
state
-
Developer-defined information to be stored in the associated
NavigationHistoryEntry
once the navigation is complete, retrievable viagetState()
. This can be any data type. You might, for example, wish to store a page visit count for analytics purposes, or store UI state details so the view can be shown exactly as the user last left it. Any data stored instate
must be structured-cloneable. info
-
Developer-defined information to be passed along to the
navigate
event, made available inNavigateEvent.info
. This can be any data type. You might, for example, wish to display newly-navigated content with a different animation depending on how it was navigated to (swipe left, swipe right, or go home). A string indicating which animation to use could be passed in asinfo
. history
-
An enumerated value that sets the history behavior of this navigation. The available values are:
auto
: The default value; will usually perform apush
navigation but will perform areplace
navigation under special circumstances (see theNotSupportedError
description below).push
: Will push a newNavigationHistoryEntry
onto the entries list, or fail under special circumstances (see theNotSupportedError
description below).replace
: Will replace the currentNavigationHistoryEntry
.
Return value
An object with the following properties:
committed
-
A
Promise
which will fulfill when the visible URL has changed and a newNavigationHistoryEntry
has been created. finished
-
A
Promise
which will fulfill when all promises returned by theintercept()
handler are fulfilled. This is equivalent to theNavigationTransition.finished
promise fulfilling, when thenavigatesuccess
event fires.
Either one of these promises rejects if the navigation has failed for some reason.
Exceptions
DataCloneError
DOMException
-
Thrown if the
state
parameter had values included in it that are not structured-cloneable. SyntaxError
DOMException
-
Thrown if the
url
parameter is not a valid URL. NotSupportedError
DOMException
-
Thrown if the
history
option is set topush
, and any of the following special circumstances are true:- The browser is currently showing the initial
about:blank
document. - The
url
's scheme isjavascript
.
- The browser is currently showing the initial
Examples
Set up home button
js
function initHomeBtn() {
// Get the key of the first loaded entry
// so the user can always go back to this view.
const { key } = navigation.currentEntry;
backToHomeButton.onclick = () => {
navigation.traverseTo(key);
};
}
// Intercept navigate events, such as link clicks, and
// replace them with single-page navigations
navigation.addEventListener("navigate", (event) => {
event.intercept({
async handler() {
// Navigate to a different view,
// but the "home" button will always work.
},
});
});
A smart back button
A page-supplied "back" button can take you back, even after reload, by inspecting the previous history entries:
js
backButtonEl.addEventListener("click", () => {
if (
navigation.entries()[navigation.currentEntry.index - 1]?.url ===
"/product-listing"
) {
navigation.back();
} else {
// If the user arrived here in some other way
// e.g. by typing the URL directly:
navigation.navigate("/product-listing", { history: "replace" });
}
});
Using info and state
js
async function navigateHandler() {
await navigation.navigate(url, {
info: { animation: "swipe-right" },
state: { infoPaneOpen: true },
});
}
Specifications
Specification |
---|
Unknown specification # dom-navigation-navigate |
Browser compatibility
BCD tables only load in the browser