HTML: The Living Standard

Edition for Web Developers — Last Updated 24 September 2023

1. 1. 7.2 APIs related to navigation and session history
      1. 7.2.1 The Window object
         1. 7.2.1.1 Opening and closing windows
         2. 7.2.1.2 Indexed access on the Window object
         3. 7.2.1.3 Named access on the Window object
         4. 7.2.1.4 Accessing related windows
         5. 7.2.1.5 Historical browser interface element APIs
      2. 7.2.2 The WindowProxy exotic object
      3. 7.2.3 The Location interface
      4. 7.2.4 The History interface
      5. 7.2.5 The navigation API
         1. 7.2.5.1 Introduction
         2. 7.2.5.2 The Navigation interface
         3. 7.2.5.3 Core infrastructure
         4. 7.2.5.4 The NavigationHistoryEntry interface
         5. 7.2.5.5 The history entry list
         6. 7.2.5.6 Initiating navigations
         7. 7.2.5.7 Ongoing navigation tracking
         8. 7.2.5.8 The navigate event
            1. 7.2.5.8.1 The NavigateEvent interface
            2. 7.2.5.8.2 The NavigationDestination interface
      6. 7.2.6 Event interfaces
         1. 7.2.6.1 The NavigationCurrentEntryChangeEvent interface
         2. 7.2.6.2 The PopStateEvent interface
         3. 7.2.6.3 The HashChangeEvent interface
         4. 7.2.6.4 The PageTransitionEvent interface
         5. 7.2.6.5 The BeforeUnloadEvent interface

7.2 APIs related to navigation and session history

7.2.1 The Window object

window.window

window.frames

window.self

These attributes all return window.

window.document

Returns the Document associated with window.

document.defaultView

Returns the Window associated with document, if there is one, or null otherwise.

7.2.1.1 Opening and closing windows

window = window.open([ url [, target [, features ] ] ])

Opens a window to show url (defaults to "about:blank"), and returns it. target (defaults to "_blank") gives the name of the new window. If a window already exists with that name, it is reused. The features argument can contain a set of comma-separated tokens:

"noopener"

"noreferrer"

These behave equivalently to the noopener and noreferrer link types on hyperlinks.

"popup"

Encourages user agents to provide a minimal web browser user interface for the new window. (Impacts the visible getter on all BarProp objects as well.)

globalThis.open("https://email.example/message/CAOOOkFcWW97r8yg=SsWg7GgCmp4suVX9o85y8BvNRqMjuc5PXg", undefined, "noopener,popup");

window.name [ = value ]

Returns the name of the window.

Can be set, to change the name.

window.close()

Closes the window.

window.closed

Returns true if the window has been closed, false otherwise.

window.stop()

Cancels the document load.

7.2.1.2 Indexed access on the Window object

window.length

Returns the number of document-tree child navigables.

window[index]

Returns the WindowProxy corresponding to the indicated document-tree child navigables.

7.2.1.3 Named access on the Window object

window[name]

Returns the indicated element or collection of elements.

As a general rule, relying on this will lead to brittle code. Which IDs end up mapping to this API can vary over time, as new features are added to the web platform, for example. Instead of this, use document.getElementById() or document.querySelector().

7.2.1.4 Accessing related windows

window.top

Returns the WindowProxy for the top-level traversable.

window.opener [ = value ]

Returns the WindowProxy for the opener browsing context.

Returns null if there isn't one or if it has been set to null.

Can be set to null.

window.parent

Returns the WindowProxy for the parent navigable.

window.frameElement

Returns the navigable container element.

Returns null if there isn't one, and in cross-origin situations.

7.2.1.5 Historical browser interface element APIs

For historical reasons, the Window interface had some properties that represented the visibility of certain web browser interface elements.

For privacy and interoperability reasons, those properties now return all return the same value: whether or not the window represents a popup window.

window.locationbar.visible

✔MDN

BarProp/visible

Support in all current engines.

Firefox1+Safari3+Chrome1+

---

Opera?Edge79+

---

Edge (Legacy)12+Internet ExplorerNo

---

Firefox Android?Safari iOS1+Chrome Android?WebView Android37+Samsung Internet?Opera Android?

window.menubar.visible

window.personalbar.visible

window.scrollbars.visible

window.statusbar.visible

window.toolbar.visible

Returns true if the Window is not a popup; otherwise, returns false.

7.2.2 The WindowProxy exotic object

A WindowProxy is an exotic object that wraps a Window ordinary object, indirecting most operations through to the wrapped object. Each browsing context has an associated WindowProxy object. When the browsing context is navigated, the Window object wrapped by the browsing context's associated WindowProxy object is changed.

7.2.3 The Location interface

Each Window object is associated with a unique instance of a Location object, allocated when the Window object is created.

document.location [ = value ]

window.location [ = value ]

Returns a Location object with the current page's location.

Can be set, to navigate to another page.

Location objects provide a representation of the URL of their associated Document, as well as methods for navigating and reloading the associated navigable.

location.toString()

location.href

Returns the Location object's URL.

Can be set, to navigate to the given URL.

location.origin

Returns the Location object's URL's origin.

location.protocol

Returns the Location object's URL's scheme.

Can be set, to navigate to the same URL with a changed scheme.

location.host

Returns the Location object's URL's host and port (if different from the default port for the scheme).

Can be set, to navigate to the same URL with a changed host and port.

location.hostname

Returns the Location object's URL's host.

Can be set, to navigate to the same URL with a changed host.

location.port

Returns the Location object's URL's port.

Can be set, to navigate to the same URL with a changed port.

location.pathname

Returns the Location object's URL's path.

Can be set, to navigate to the same URL with a changed path.

location.search

Returns the Location object's URL's query (includes leading "?" if non-empty).

Can be set, to navigate to the same URL with a changed query (ignores leading "?").

location.hash

Returns the Location object's URL's fragment (includes leading "#" if non-empty).

Can be set, to navigate to the same URL with a changed fragment (ignores leading "#").

location.assign(url)

Navigates to the given URL.

location.replace(url)

Removes the current page from the session history and navigates to the given URL.

location.reload()

Reloads the current page.

location.ancestorOrigins

Returns a DOMStringList object listing the origins of the ancestor navigables' active documents.

7.2.4 The History interface

history.length

Returns the number of overall session history entries for the current traversable navigable.

history.scrollRestoration

Returns the scroll restoration mode of the active session history entry.

history.scrollRestoration = value

Set the scroll restoration mode of the active session history entry to value.

history.state

Returns the classic history API state of the active session history entry, deserialized into a JavaScript value.

history.go()

Reloads the current page.

history.go(delta)

Goes back or forward the specified number of steps in the overall session history entries list for the current traversable navigable.

A zero delta will reload the current page.

If the delta is out of range, does nothing.

history.back()

Goes back one step in the overall session history entries list for the current traversable navigable.

If there is no previous page, does nothing.

history.forward()

Goes forward one step in the overall session history entries list for the current traversable navigable.

If there is no next page, does nothing.

history.pushState(data, "")

Adds a new entry into session history with its classic history API state set to a serialization of data. The active history entry's URL will be copied over and used for the new entry's URL.

(The second parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional.)

history.pushState(data, "", url)

Adds a new entry into session history with its classic history API state set to a serialization of data, and with its URL set to url.

If the current Document cannot have its URL rewritten to url, a "SecurityError" DOMException will be thrown.

(The second parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional.)

history.replaceState(data, "")

Updates the classic history API state of the active session history entry to a structured clone of data.

(The second parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional.)

history.replaceState(data, "", url)

Updates the classic history API state of the active session history entry to a structured clone of data, and its URL to url.

If the current Document cannot have its URL rewritten to url, a "SecurityError" DOMException will be thrown.

(The second parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional.)

<!DOCTYPE HTML>
<!-- this is https://example.com/line?x=5 -->
<html lang="en">
<title>Line Game - 5</title>
<p>You are at coordinate 5 on the line.</p>
<p>
 <a href="?x=6">Advance to 6</a> or
 <a href="?x=4">retreat to 4</a>?
</p>

<!DOCTYPE HTML>
<!-- this starts off as https://example.com/line?x=5 -->
<html lang="en">
<title>Line Game - 5</title>
<p>You are at coordinate <span id="coord">5</span> on the line.</p>
<p>
 <a href="?x=6" onclick="go(1); return false;">Advance to 6</a> or
 <a href="?x=4" onclick="go(-1); return false;">retreat to 4</a>?
</p>
<script>
 var currentPage = 5; // prefilled by server
 function go(d) {
   setupPage(currentPage + d);
   history.pushState(currentPage, "", '?x=' + currentPage);
 }
 onpopstate = function(event) {
   setupPage(event.state);
 }
 function setupPage(page) {
   currentPage = page;
   document.title = 'Line Game - ' + currentPage;
   document.getElementById('coord').textContent = currentPage;
   document.links[0].href = '?x=' + (currentPage+1);
   document.links[0].textContent = 'Advance to ' + (currentPage+1);
   document.links[1].href = '?x=' + (currentPage-1);
   document.links[1].textContent = 'retreat to ' + (currentPage-1);
 }
</script>

<head>
  <script>
       if ('scrollRestoration' in history)
            history.scrollRestoration = 'manual';
  </script>
</head>
   

7.2.5 The navigation API

7.2.5.1 Introduction

The navigation API, provided by the global navigation property, provides a modern and web application-focused way of managing navigations and history entries. It is a successor to the classic location and history APIs.

One ability the API provides is inspecting session history entries. For example, the following will display the entries' URLs in an ordered list:

const ol = document.createElement("ol");
ol.start = 0; // so that the list items' ordinal values match up with the entry indices

for (const entry of navigation.entries()) {
  const li = document.createElement("li");

  if (entry.index < navigation.currentEntry.index) {
    li.className = "backward";
  } else if (entry.index > navigation.currentEntry.index) {
    li.className = "forward";
  } else {
    li.className = "current";
  }

  li.textContent = entry.url;
  ol.append(li);
}

The navigation.entries() array contains NavigationHistoryEntry instances, which have other useful properties in addition to the url and index properties shown here. Note that the array only contains NavigationHistoryEntry objects that represent the current navigable, and thus its contents are not impacted by navigations inside navigable containers such as iframes, or by navigations of the parent navigable in cases where the navigation API is itself being used inside an iframe. Additionally, it only contains NavigationHistoryEntry objects representing same-origin session history entries, meaning that if the user has visited other origins before or after the current one, there will not be corresponding NavigationHistoryEntrys.

The navigation API can also be used to navigate, reload, or traverse through the history:

<button onclick="navigation.reload()">Reload</button>

<input type="url" id="navigationURL">
<button onclick="navigation.navigate(navigationURL.value)">Navigate</button>

<button id="backButton" onclick="navigation.back()">Back</button>
<button id="forwardButton" onclick="navigation.forward()">Forward</button>

<select id="traversalDestinations"></select>
<button id="goButton" onclick="navigation.traverseTo(traversalDestinations.value)">Traverse To</button>

<script>
backButton.disabled = !navigation.canGoBack;
forwardButton.disabled = !navigation.canGoForward;

for (const entry of navigation.entries()) {
  traversalDestinations.append(new Option(entry.url, entry.key));
}
</script>

Note that traversals are again limited to same-origin destinations, meaning that, for example, navigation.canGoBack will be false if the previous session history entry is for a page from another origin.

The most powerful part of the navigation API is the navigate event, which fires whenever almost any navigation or traversal occurs in the current navigable:

navigation.onnavigate = event => {
  console.log(event.navigationType); // "push", "replace", "reload", or "traverse"
  console.log(event.destination.url);
  console.log(event.userInitiated);
  // ... and other useful properties
};

(The event will not fire for location bar-initiated navigations, or navigations initiated from other windows, when the destination of the navigation is a new document.)

Much of the time, the event's cancelable property will be true, meaning this event can be canceled using preventDefault():

navigation.onnavigate = event => {
  if (event.cancelable && isDisallowedURL(event.destination.url)) {
    alert(`Please don't go to ${event.destination.url}!`);
    event.preventDefault();
  }
};

The cancelable property will be false for some "traverse" navigations, such as those taking place inside child navigables, those crossing to new origins, or when the user attempts to traverse again shortly after a previous call to preventDefault() prevented them from doing so.

The NavigateEvent's intercept() method allows intercepting a navigation and converting it into a same-document navigation:

navigation.addEventListener("navigate", e => {
  // Some navigations, e.g. cross-origin navigations, we cannot intercept.
  // Let the browser handle those normally.
  if (!e.canIntercept) {
    return;
  }

  // Similarly, don't intercept fragment navigations or downloads.
  if (e.hashChange || e.downloadRequest !== null) {
    return;
  }

  const url = new URL(event.destination.url);

  if (url.pathname.startsWith("/articles/")) {
    e.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, { signal: e.signal });
        renderArticlePage(articleContent);
      }
    });
  }
});

Note that the handler function can return a promise to represent the asynchronous progress, and success or failure, of the navigation. While the promise is still pending, browser UI can treat the navigation as ongoing (e.g., by presenting a loading spinner). Other parts of the navigation API are also sensitive to these promises, such as the return value of navigation.navigate():

const { committed, finished } = await navigation.navigate("/articles/the-navigation-api-is-cool");

// The committed promise will fulfill once the URL has changed, which happens
// immediately (as long as the NavigateEvent wasn't canceled).
await committed;

// The finished promise will fulfill once the Promise returned by handler() has
// fulfilled, which happens once the article is downloaded and rendered. (Or,
// it will reject, if handler() fails along the way).
await finished;

7.2.5.2 The Navigation interface

The following are the event handlers (and their corresponding event handler event types) supported, as event handler IDL attributes, by all objects implementing the Navigation interface:

7.2.5.3 Core infrastructure

A key type used throughout the navigation API is the NavigationType enumeration:

This captures the main web developer-visible types of "navigations", which (as noted elsewhere) do not exactly correspond to this standard's singular navigate algorithm. The meaning of each value is the following:

"push"

Corresponds to calls to navigate where the history handling behavior ends up as "push", or to history.pushState().

"replace"

Corresponds to calls to navigate where the history handling behavior ends up as "replace", or to history.replaceState().

"reload"

Corresponds to calls to reload.

"traverse"

Corresponds to calls to traverse the history by a delta.

7.2.5.4 The NavigationHistoryEntry interface

entry.url

The URL of this navigation history entry.

This can return null if the entry corresponds to a different Document than the current one (i.e., if sameDocument is false), and that Document was fetched with a referrer policy of "no-referrer" or "origin", since that indicates the Document in question is hiding its URL even from other same-origin pages.

entry.key

A user agent-generated random UUID string representing this navigation history entry's place in the navigation history list. This value will be reused by other NavigationHistoryEntry instances that replace this one due to "replace" navigations, and will survive reloads and session restores.

This is useful for navigating back to this entry in the navigation history list, using navigation.traverseTo(key).

entry.id

A user agent-generated random UUID string representing this specific navigation history entry. This value will not be reused by other NavigationHistoryEntry instances. This value will survive reloads and session restores.

This is useful for associating data with this navigation history entry using other storage APIs.

entry.index

The index of this NavigationHistoryEntry within navigation.entries(), or −1 if the entry is not in the navigation history entry list.

entry.sameDocument

Indicates whether or not this navigation history entry is for the same Document as the current one, or not. This will be true, for example, when the entry represents a fragment navigation or single-page app navigation.

entry.getState()

Returns the deserialization of the state stored in this entry, which was added to the entry using navigation.navigate() or navigation.updateCurrentEntry(). This state survives reloads and session restores.

Note that in general, unless the state value is a primitive, entry.getState() !== entry.getState(), since a fresh deserialization is returned each time.

This state is unrelated to the classic history API's history.state.

The following are the event handlers (and their corresponding event handler event types) supported, as event handler IDL attributes, by all objects implementing the NavigationHistoryEntry interface:

7.2.5.5 The history entry list

entries = navigation.entries()

Returns an array of NavigationHistoryEntry instances represent the current navigation history entry list, i.e., all session history entries for this navigable that are same origin and contiguous to the current session history entry.

navigation.currentEntry

Returns the NavigationHistoryEntry corresponding to the current session history entry.

navigation.updateCurrentEntry({ state })

Updates the navigation API state of the current session history entry, without performing a navigation like navigation.reload() would do.

This method is best used to capture updates to the page that have already happened, and need to be reflected into the navigation API state. For cases where the state update is meant to drive a page update, instead use navigation.navigate() or navigation.reload(), which will trigger a navigate event.

navigation.canGoBack

Returns true if the current current session history entry (i.e., currentEntry) is not the first one in the navigation history entry list (i.e., in entries()). This means that there is a previous session history entry for this navigable, and its document state's origin is same origin with the current Document's origin.

navigation.canGoForward

Returns true if the current current session history entry (i.e., currentEntry) is not the last one in the navigation history entry list (i.e., in entries()). This means that there is a next session history entry for this navigable, and its document state's origin is same origin with the current Document's origin.

7.2.5.6 Initiating navigations

{ committed, finished } = navigation.navigate(url)

{ committed, finished } = navigation.navigate(url, options)

Navigates the current page to the given url. options can contain the following values:

• history can be set to "replace" to replace the current session history entry, instead of pushing a new one.

• info can be set to any value; it will populate the info property of the corresponding NavigateEvent.

• state can be set to any serializable value; it will populate the state retrieved by navigation.currentEntry.getState() once the navigation completes, for same-document navigations. (It will be ignored for navigations that end up cross-document.)

By default this will perform a full navigation (i.e., a cross-document navigation, unless the given URL differs only in a fragment from the current one). The navigateEvent.intercept() method can be used to convert it into a same-document navigation.

The returned promises will behave as follows:

• For navigations that get aborted, both promises will reject with an "AbortError" DOMException.

• For same-document navigations created by using the navigateEvent.intercept() method, committed will fulfill immediately, and finished will fulfill or reject according to any promsies returned by handlers passed to intercept().

• For other same-document navigations (e.g., non-intercepted fragment navigations), both promises will fulfill immediately.

• For cross-document navigations, or navigations that result in 204 or 205 statuses or `Content-Disposition: attachment` header fields from the server (and thus do not actually navigate), both promises will never settle.

In all cases, when the returned promises fulfill, it will be with the NavigationHistoryEntry that was navigated to.

{ committed, finished } = navigation.reload(options)

Reloads the current page. options can contain info and state, which behave as described above.

The default behavior of performing a from-network-or-cache reload of the current page can be overriden by the using the navigateEvent.intercept() method. Doing so will mean this call only updates state or passes along the appropriate info, plus performing whater actions the navigate event handlers see fit to carry out.

The returned promises will behave as follows:

• If the reload is intercepted by using the navigateEvent.intercept() method, committed will fulfill immediately, and finished will fulfill or reject according to any promsies returned by handlers passed to intercept().

• Otherwise, both promises will never settle.

{ committed, finished } = navigation.traverseTo(key)

{ committed, finished } = navigation.traverseTo(key, { info })

Traverses to the closest session history entry that matches the NavigationHistoryEntry with the given key. info can be set to any value; it will populate the info property of the corresponding NavigateEvent.

If a traversal to that session history entry is already in progress, then this will return the promises for that original traversal, and info will be ignored.

The returned promises will behave as follows:

• If there is no NavigationHistoryEntry in navigation.entries() whose key matches key, both promises will reject with an "InvalidStateError" DOMException.

• For same-document traversals intercepted by the navigateEvent.intercept() method, committed will fulfill as soon as the traversal is processed and navigation.currentEntry is updated, and finished will fulfill or reject according to any promsies returned by the handlers passed to intercept().

• For non-intercepted same-document travesals, both promises will fulfill as soon as the traversal is processed and navigation.currentEntry is updated.

• For cross-document traversals, including attempted cross-document traversals that end up resulting in a 204 or 205 statuses or `Content-Disposition: attachment` header fields from the server (and thus do not actually traverse), both promises will never settle.

{ committed, finished } = navigation.back(key)

{ committed, finished } = navigation.back(key, { info })

Traverses to the closest previous session history entry which results in this navigable traversing, i.e., which corresponds to a different NavigationHistoryEntry and thus will cause navigation.currentEntry to change. info can be set to any value; it will populate the info property of the corresponding NavigateEvent.

If a traversal to that session history entry is already in progress, then this will return the promises for that original traversal, and info will be ignored.

The returned promises behave equivalently to those returned by traverseTo().

{ committed, finished } = navigation.forward(key)

{ committed, finished } = navigation.forward(key, { info })

Traverses to the closest forward session history entry which results in this navigable traversing, i.e., which corresponds to a different NavigationHistoryEntry and thus will cause navigation.currentEntry to change. info can be set to any value; it will populate the info property of the corresponding NavigateEvent.

If a traversal to that session history entry is already in progress, then this will return the promises for that original traversal, and info will be ignored.

The returned promises behave equivalently to those returned by traverseTo().

7.2.5.7 Ongoing navigation tracking

navigation.transition

A NavigationTransition representing any ongoing navigation that hasn't yet reached the navigatesuccess or navigateerror stage, if one exists; or null, if there is no such transition ongoing.

Since navigation.currentEntry (and other properties like location.href) are updated immediately upon navigation, this navigation.transition property is useful for determining when such navigations are not yet fully settled, according to any handlers passed to navigateEvent.intercept().

navigation.transition.navigationType

One of "push", "replace", "reload", or "traverse", indicating what type of navigation this transition is for.

navigation.transition.from

The NavigationHistoryEntry from which the transition is coming. This can be useful to compare against navigation.currentEntry.

navigation.transition.finished

A promise which fulfills at the same time as the navigatesuccess fires, or rejects at the same time the navigateerror event fires.

7.2.5.8 The navigate event

A major feature of the navigation API is the navigate event. This event is fired on any navigation (in the broad sense of the word), allowing web developers to monitor such outgoing navigations. In many cases, the event is cancelable, which allows preventing the navigation from happening. And in others, the navigation can be intercepted and replaced with a same-document navigation by using the intercept() method of the NavigateEvent class.

7.2.5.8.1 The NavigateEvent interface

event.navigationType

One of "push", "replace", "reload", or "traverse", indicating what type of navigation this is.

event.destination

A NavigationDestination representing the destination of the navigation.

event.canIntercept

True if intercept() can be called to intercept this navigation and convert it into a same-document navigation, replacing its usual behavior; false otherwise.

Generally speaking, this will be true whenever the current Document can have its URL rewritten to the destination URL, except for in the case of cross-document "traverse" navigations, where it will always be false.

event.userInitiated

True if this navigation was due to a user clicking on an a element, submitting a form element, or using the browser UI to navigate; false otherwise.

event.hashChange

True for a fragment navigation; false otherwise.

event.signal

An AbortSignal which will become aborted if the navigation gets canceled, e.g., by the user pressing their browser's "Stop" button, or by another navigation interrupting this one.

The expected pattern is for developers to pass this along to any async operations, such as fetch(), which they perform as part of handling this navigation.

event.formData

The FormData representing the submitted form entries for this navigation, if this navigation is a "push" or "replace" navigation representing a POST form submission; null otherwise.

(Notably, this will be null even for "reload" or "traverse" navigations that are revisiting a session history entry that was originally created from a form submission.)

event.downloadRequest

Represents whether or not this navigation was requested to be a download, by using an a or area element's download attribute:

• If a download was not requested, then this property is null.

• If a download was requested, returns the filename that was supplied as the download attribute's value. (This could be the empty string.)

Note that a download being requested does not always mean that a download will happen: for example, a download might be blocked by browser security policies, or end up being treated as a "push" navigation for unspecified reasons.

Similarly, a navigation might end up being a download even if it was not requested to be one, due to the destination server responding with a `Content-Disposition: attachment` header.

Finally, note that the navigate event will not fire at all for downloads initiated using browser UI affordances, e.g., those created by right-clicking and choosing to save the target of a link.

event.info

An arbitrary JavaScript value passed via one of the navigation API methods which initiated this navigation, or undefined if the navigation was initiated by the user or by a different API.

event.hasUAVisualTransition

Returns true if the user agent performed a visual transition for this navigation before dispatching this event. If true, the best user experience will be given if the author synchronously updates the DOM to the post-navigation state.

event.intercept({ handler, focusReset, scroll })

Intercepts this navigation, preventing its normal handling and instead converting it into a same-document navigation of the same type to the destination URL.

The handler option can be a function that returns a promise. The handler function will run after the navigate event has finished firing, and the navigation.currentEntry property has been synchronously updated. This returned promise is used to signal the duration, and success or failure, of the navigation. After it settles, the browser signals to the user (e.g., via a loading spinner UI, or assistive technology) that the navigation is finished. Additionally, it fires navigatesuccess or navigateerror events as appropriate, which other parts of the web application can respond to.

By default, using this method will cause focus to reset when any handlers' returned promises settle. Focus will be reset to the first element with the autofocus attribute set, or the body element if the attribute isn't present. The focusReset option can be set to "manual" to avoid this behavior.

By default, using this method will delay the browser's scroll restoration logic for "traverse" or "reload" navigations, or its scroll-reset/scroll-to-a-fragment logic for "push" or "replace" navigations, until any handlers' returned promises settle. The scroll option can be set to "manual" to turn off any browser-driven scroll behavior entirely for this navigation, or scroll() can be called before the promise settles to trigger this behavior early.

This method will throw a "SecurityError" DOMException if canIntercept is false, or if isTrusted is false. It will throw an "InvalidStateError" DOMException if not called synchronously, during event dispatch.

event.scroll()

For "traverse" or "reload" navigations, restores the scroll position using the browser's usual scroll restoration logic.

For "push" or "replace" navigations, either resets the scroll position to the top of the document or scrolls to the fragment specified by destination.url if there is one.

If called more than once, or called after automatic post-transition scroll processing has happened due to the scroll option being left as "after-transition", or called before the navigation has committed, this method will throw an "InvalidStateError" DOMException.

7.2.5.8.2 The NavigationDestination interface

event.destination.url

The URL being navigated to.

event.destination.key

The value of the key property of the destination NavigationHistoryEntry, if this is a "traverse" navigation, or the empty string otherwise.

event.destination.id

The value of the id property of the destination NavigationHistoryEntry, if this is a "traverse" navigation, or the empty string otherwise.

event.destination.index

The value of the index property of the destination NavigationHistoryEntry, if this is a "traverse" navigation, or −1 otherwise.

event.destination.sameDocument

Indicates whether or not this navigation is to the same Document as the current one, or not. This will be true, for example, in the case of fragment navigations or history.pushState() navigations.

Note that this property indicates the original nature of the navigation. If a cross-document navigation is converted into a same-document navigation using navigateEvent.intercept(), that will not change the value of this property.

event.destination.getState()

For "traverse" navigations, returns the deserialization of the state stored in the destination session history entry.

For "push" or "replace" navigations, returns the deserialization of the state passed to navigation.navigate(), if the navigation was initiated by that method, or undefined it if it wasn't.

For "reload" navigations, returns the deserialization of the state passed to navigation.reload(), if the reload was initiated by that method, or undefined it if it wasn't.

7.2.6 Event interfaces

The NavigateEvent interface has its own dedicated section, due to its complexity.

7.2.6.1 The NavigationCurrentEntryChangeEvent interface

event.navigationType

Returns the type of navigation which caused the current entry to change, or null if the change is due to navigation.updateCurrentEntry().

event.from

Returns the previous value of navigation.currentEntry, before the current entry changed.

If navigationType is null or "reload", then this value will be the same as navigation.currentEntry. In that case, the event signifies that the contents of the entry changed, even if we did not move to a new entry or replace the current one.

7.2.6.2 The PopStateEvent interface

event.state

Returns a copy of the information that was provided to pushState() or replaceState().

event.hasUAVisualTransition

Returns true if the user agent performed a visual transition for this navigation before dispatching this event. If true, the best user experience will be given if the author synchronously updates the DOM to the post-navigation state.

7.2.6.3 The HashChangeEvent interface

event.oldURL

Returns the URL of the session history entry that was previously current.

event.newURL

Returns the URL of the session history entry that is now current.

7.2.6.4 The PageTransitionEvent interface

event.persisted

For the pageshow event, returns false if the page is newly being loaded (and the load event will fire). Otherwise, returns true.

For the pagehide event, returns false if the page is going away for the last time. Otherwise, returns true, meaning that the page might be reused if the user navigates back to this page (if the Document's salvageable state stays true).

Things that can cause the page to be unsalvageable include:

• The user agent decided to not keep the Document alive in a session history entry after unload
• Having iframes that are not salvageable
• Active WebSocket objects
• Aborting a Document

7.2.6.5 The BeforeUnloadEvent interface

There are no BeforeUnloadEvent-specific initialization methods.

The BeforeUnloadEvent interface is a legacy interface which allows checking if unloading is canceled to be controlled not only by canceling the event, but by setting the returnValue attribute to a value besides the empty string. Authors should use the preventDefault() method, or other means of canceling events, instead of using returnValue.