HTML: The Living Standard

Edition for Web Developers — Last Updated 29 March 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 Event interfaces
         1. 7.2.5.1 The PopStateEvent interface
         2. 7.2.5.2 The HashChangeEvent interface
         3. 7.2.5.3 The PageTransitionEvent interface
         4. 7.2.5.4 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 serialized 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 serialized 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 serialized 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 serialized 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 serialized 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 Event interfaces

7.2.5.1 The PopStateEvent interface

event.state

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

7.2.5.2 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.5.3 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.5.4 The BeforeUnloadEvent interface

There are no BeforeUnloadEvent-specific initialization methods.

The BeforeUnloadEvent interface is a legacy interface which allows checking if unloading is user-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.