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.1 The Window object

Window

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android10.1+
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().

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

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

Document/location

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+

Location

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android10.1+

Window/location

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+

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

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+

Window/history

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+
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.)

document's URL targetURL can have its URL rewritten
https://example.com/home https://example.com/home#about
https://example.com/home https://example.com/home?page=shop
https://example.com/home https://example.com/shop
https://example.com/home https://user:pass@example.com/home
https://example.com/home http://example.com/home
file:///path/to/x file:///path/to/x#hash
file:///path/to/x file:///path/to/x?search
file:///path/to/x file:///path/to/y
about:blank about:blank#hash
about:blank about:blank?search
about:blank about:srcdoc
data:text/html,foo data:text/html,foo#hash
data:text/html,foo data:text/html,foo?search
data:text/html,foo data:text/html,bar
data:text/html,foo data:bar
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43#hash
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43?search
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 blob:https://example.com/anything
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 blob:path

Note how only the URL of the Document matters, and not its origin. They can mismatch in cases like about:blank Documents with inherited origins, in sandboxed iframes, or when the document.domain setter has been used.

Consider a game where the user can navigate along a line, such that the user is always at some coordinate, and such that the user can bookmark the page corresponding to a particular coordinate, to return to it later.

A static page implementing the x=5 position in such a game could look like the following:

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

The problem with such a system is that each time the user clicks, the whole page has to be reloaded. Here instead is another way of doing it, using script:

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

In systems without script, this still works like the previous example. However, users that do have script support can now navigate much faster, since there is no network access for the same experience. Furthermore, contrary to the experience the user would have with just a naïve script-based approach, bookmarking and navigating the session history still work.

In the example above, the data argument to the pushState() method is the same information as would be sent to the server, but in a more convenient form, so that the script doesn't have to parse the URL each time the user navigates.

Most applications want to use the same scroll restoration mode value for all of their history entries. To achieve this they can set the scrollRestoration attribute as soon as possible (e.g., in the first script element in the document's head element) to ensure that any entry added to the history session gets the desired scroll restoration mode.

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

PopStateEvent/PopStateEvent

Support in all current engines.

Firefox11+Safari6+Chrome16+
Opera?Edge79+
Edge (Legacy)14+Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

PopStateEvent

Support in all current engines.

Firefox4+Safari6+Chrome4+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+
event.state

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

7.2.5.2 The HashChangeEvent interface

HashChangeEvent/HashChangeEvent

Support in all current engines.

Firefox11+Safari6+Chrome16+
Opera?Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

HashChangeEvent

Support in all current engines.

Firefox3.6+Safari5+Chrome8+
Opera10.6+Edge79+
Edge (Legacy)12+Internet Explorer8+
Firefox Android?Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android11+
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

PageTransitionEvent/PageTransitionEvent

Support in all current engines.

Firefox11+Safari6+Chrome16+
Opera?Edge79+
Edge (Legacy)?Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

PageTransitionEvent

Support in all current engines.

Firefox1.5+Safari5+Chrome4+
Opera?Edge79+
Edge (Legacy)12+Internet Explorer11
Firefox Android?Safari iOS4+Chrome Android?WebView Android37+Samsung Internet?Opera Android?
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:

7.2.5.4 The BeforeUnloadEvent interface

BeforeUnloadEvent

Support in all current engines.

Firefox1.5+Safari7+Chrome30+
Opera?Edge79+
Edge (Legacy)?Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet3.0+Opera Android?

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.