1. 7.7 Session history and navigation
      1. 7.7.1 Browsing sessions
      2. 7.7.2 The session history of browsing contexts
      3. 7.7.3 The History interface
      4. 7.7.4 The Location interface

7.7 Session history and navigation

History/back

Support in all current engines.

FirefoxYesSafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet Explorer10+
Firefox AndroidYesSafari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

History/forward

Support in all current engines.

FirefoxYesSafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet Explorer10+
Firefox AndroidYesSafari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

7.7.1 Browsing sessions

A browsing session is …. See whatwg/html issue #4782 and whatwg/html issue #5350 for defining browsing session. It is roughly analogous to a top-level browsing context except that it cannot be replaced due to a `Cross-Origin-Opener-Policy` header or navigation.

A top-level browsing context has an associated browsing session which is a browsing session.

The browsing session of an environment settings object environment is the result of running these steps:

  1. Assert: environment has a responsible document.

  2. Return environment's responsible document's browsing context's top-level browsing context's browsing session.

7.7.2 The session history of browsing contexts

The sequence of Documents in a browsing context is its session history. Each browsing context, including child browsing contexts, has a distinct session history. A browsing context's session history consists of a flat list of session history entries.

Each Document object in a browsing context's session history is associated with a unique History object which must all model the same underlying session history.


A session history entry is a struct with the following items:

Serialized state is a serialization (via StructuredSerializeForStorage) of an object representing a user interface state. We sometimes informally refer to "state objects", which are the objects representing user interface state supplied by the author, or alternately the objects created by deserializing (via StructuredDeserialize) serialized state.

Pages can add serialized state to the session history. These are then deserialized and returned to the script when the user (or script) goes back in the history, thus enabling authors to use the "navigation" metaphor even in one-page applications.

Serialized state is intended to be used for two main purposes: first, storing a preparsed description of the state in the URL so that in the simple case an author doesn't have to do the parsing (though one would still need the parsing for handling URLs passed around by users, so it's only a minor optimization). Second, so that the author can store state that one wouldn't store in the URL because it only applies to the current Document instance and it would have to be reconstructed if a new Document were opened.

An example of the latter would be something like keeping track of the precise coordinate from which a popup div was made to animate, so that if the user goes back, it can be made to animate to the same location. Or alternatively, it could be used to keep a pointer into a cache of data that would be fetched from the server based on the information in the URL, so that when going back and forward, the information doesn't have to be fetched again.

History/scrollRestoration

Support in all current engines.

Firefox46+SafariYesChrome46+
Opera33+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox AndroidYesSafari iOSYesChrome Android46+WebView AndroidNoSamsung Internet5.0+Opera AndroidYes

A scroll restoration mode indicates whether the user agent should restore the persisted scroll position (if any) when traversing to an entry. A scroll restoration mode is one of the following:

"auto"
The user agent is responsible for restoring the scroll position upon navigation.
"manual"
The page is responsible for restoring the scroll position and the user agent does not attempt to do so automatically

Several contiguous entries in a session history can share the same document. This can occur when the initial entry is reached via normal navigation, and the following entry is added via history.pushState(). Or it can occur via navigation to a fragment.

All entries that share the same document (and that are therefore merely different states of one particular document) are contiguous by definition.


At any point, one of the entries in the session history is the current entry. This is the entry representing the active document of the browsing context. Which entry is the current entry is changed by the algorithms defined in this specification, e.g., during session history traversal.

The current entry is usually the initial entry created upon navigation. However, it can also be one of the contiguous entries that share the same document, as described above.

Each Document in a browsing context can also have a latest entry. This is the entry for that Document to which the browsing context's session history was most recently traversed. When a Document is created, it initially has no latest entry.

7.7.3 The History interface

History

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+

Window/history

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+
window . history . length

History/length

Support in all current engines.

FirefoxYesSafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet Explorer10+
Firefox AndroidYesSafari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

Returns the number of entries in the joint session history.

window . history . scrollRestoration [ = value ]

Returns the scroll restoration mode of the current entry in the session history.

Can be set, to change the scroll restoration mode of the current entry in the session history.

window . history . state

Returns the current serialized state, deserialized into an object.

window . history . go( [ delta ] )

History/go

Support in all current engines.

FirefoxYesSafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet Explorer10+
Firefox AndroidYesSafari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

Goes back or forward the specified number of steps in the joint session history.

A zero delta will reload the current page.

If the delta is out of range, does nothing.

window . history . back()

Goes back one step in the joint session history.

If there is no previous page, does nothing.

window . history . forward()

Goes forward one step in the joint session history.

If there is no next page, does nothing.

window . history . pushState(data, title [, url ] )

History/pushState

Support in all current engines.

Firefox4+Safari5+Chrome5+
Opera11.5+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android4+Safari iOS4.3+Chrome Android18+WebView Android37+Samsung Internet1.0+Opera Android11.5+
caniuse.com table

Pushes the given data onto the session history, with the given title, and, if provided and not null, the given URL.

window . history . replaceState(data, title [, url ] )

History/replaceState

Support in all current engines.

Firefox4+Safari5+Chrome5+
Opera11.5+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android4+Safari iOS4.3+Chrome Android18+WebView Android37+Samsung Internet1.0+Opera Android11.5+

Updates the current entry in the session history to have the given data, title, and, if provided and not null, URL.

The joint session history of a top-level browsing context is the union of all the session histories of all browsing contexts of all the fully active Document objects that share that top-level browsing context, with all the entries that are current entries in their respective session histories removed except for the current entry of the joint session history.

The current entry of the joint session history is the entry that most recently became a current entry in its session history.

Entries in the joint session history are ordered chronologically by the time they were added to their respective session histories. Each entry has an index; the earliest entry has index 0, and the subsequent entries are numbered with consecutively increasing integers (1, 2, 3, etc).

Since each Document in a browsing context might have a different event loop, the actual state of the joint session history can be somewhat nebulous. For example, two sibling iframe elements could both traverse from one unique origin to another at the same time, so their precise order might not be well-defined; similarly, since they might only find out about each other later, they might disagree about the length of the joint session history.

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, document.title, '?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.

Applications might not use the same title for a session history entry as the value of the document's title element at that time. For example, here is a simple page that shows a block in the title element. Clearly, when navigating backwards to a previous state the user does not go back in time, and therefore it would be inappropriate to put the time in the session history title.

<!DOCTYPE HTML>
<HTML LANG=EN>
<TITLE>Line</TITLE>
<SCRIPT>
 setInterval(function () { document.title = 'Line - ' + new Date(); }, 1000);
 var i = 1;
 function inc() {
   set(i+1);
   history.pushState(i, 'Line - ' + i);
 }
 function set(newI) {
   i = newI;
   document.forms.F.I.value = newI;
 }
</SCRIPT>
<BODY ONPOPSTATE="set(event.state)">
<FORM NAME=F>
State: <OUTPUT NAME=I>1</OUTPUT> <INPUT VALUE="Increment" TYPE=BUTTON ONCLICK="inc()">
</FORM>

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.7.4 The Location interface

Document/location

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+

Location

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+

Window/location

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+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 the active document of their Document's browsing context, and allow the current entry of the browsing context's session history to be changed, by adding or replacing entries in the history object.

location . toString()
location . href

Location/href

Support in all current engines.

Firefox22+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet ExplorerYes
Firefox Android22+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

Location/toString

Firefox22+Safari?Chrome52+
Opera?Edge79+
Edge (Legacy)12+Internet Explorer11
Firefox Android22+Safari iOS?Chrome Android52+WebView Android52+Samsung Internet6.0+Opera Android?

Returns the Location object's URL.

Can be set, to navigate to the given URL.

location . origin

Location/origin

Support in all current engines.

Firefox26+SafariYesChromeYes
Opera10+EdgeYes
Edge (Legacy)12+Internet Explorer11
Firefox Android26+Safari iOS5+Chrome AndroidYesWebView AndroidYesSamsung InternetYesOpera Android?

Returns the Location object's URL's origin.

location . protocol

Location/protocol

Support in all current engines.

Firefox22+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet ExplorerYes
Firefox Android22+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

Returns the Location object's URL's scheme.

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

location . host

Location/host

Support in all current engines.

Firefox22+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet ExplorerYes
Firefox Android22+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

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

Location/hostname

Support in all current engines.

Firefox22+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet ExplorerYes
Firefox Android22+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

Returns the Location object's URL's host.

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

location . port

Location/port

Support in all current engines.

Firefox22+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet ExplorerYes
Firefox Android22+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

Returns the Location object's URL's port.

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

location . pathname

Location/pathname

Support in all current engines.

Firefox22+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet ExplorerYes
Firefox Android22+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

Returns the Location object's URL's path.

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

location . search

Location/search

Support in all current engines.

Firefox22+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet ExplorerYes
Firefox Android22+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

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

Location/hash

Support in all current engines.

Firefox22+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet ExplorerYes
Firefox Android22+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

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)

Location/assign

Support in all current engines.

Firefox1+Safari3+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer5.5+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+

Navigates to the given URL.

location . replace(url)

Location/replace

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer5.5+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+

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

location . reload()

Location/reload

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer5.5+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+

Reloads the current page.

location . ancestorOrigins

Location/ancestorOrigins

FirefoxNoSafari6+Chrome20+
Opera15+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox AndroidNoSafari iOS6+Chrome Android25+WebView Android4.4+Samsung Internet1.5+Opera Android14+

Returns a DOMStringList object listing the origins of the ancestor browsing contexts, from the parent browsing context to the top-level browsing context.