Window.history

  • Revision slug: DOM/window.history
  • Revision title: window.history
  • Revision id: 61567
  • Created:
  • Creator: jswisher
  • Is current revision? No
  • Comment 8 words added

Revision Content

{{ DomRef() }}

{{ DevDerbyPromoHeader("the History API") }}

Summary

Returns a reference to the History object, which provides an interface for manipulating the browser session history (pages visited in the tab or frame that the current page is loaded in).

Syntax

var historyObj = window.history;

The obtained History object has the following methods:

Method Description Return value
history.back()

Goes to the previous page in session history, the same action as when the user clicks the browser's Back button. Equivalent to history.go(-1).

Note: Calling this method to go back beyond the first page in the session history has no effect and doesn't raise an exception.
No return value
history.forward()

Goes to the next page in session history, the same action as when the user clicks the browser's Forward button; this is equivalent to history.go(1).

Note: Calling this method to go back beyond the last page in the session history has no effect and doesn't raise an exception.
No return value
history.go(integerDelta) Loads a page from the session history, identified by its relative location to the current page, for example -1 for the previous page or 1 for the next page. When integerDelta is out of bounds (e.g. -1 when there are no previously visited pages in the session history), the method doesn't do anything and doesn't raise an exception. Calling go() without parameters or with a non-integer argument has no effect (unlike Internet Explorer, which supports string URLs as the argument). No return value
history.pushState(data, title [, url]) {{ gecko_minversion_inline("2.0") }}

Pushes the given data onto the session history stack with the specified title and, if provided, URL. The data is treated as opaque by the DOM; you may specify any JavaScript object that can be serialized.  Note that Firefox currently ignores the title parameter; for more information, see manipulating the browser history.

Note: In Gecko 2.0 {{ geckoRelease("2.0") }} through Gecko 5.0 {{ geckoRelease("5.0") }}, the passed object is serialized using JSON. Starting in Gecko 6.0 {{ geckoRelease("6.0") }}, the object is serialized using the structured clone algorithm. This allows a wider variety of objects to be safely passed.
No return value
history.replaceState(data, title [, url]) {{ gecko_minversion_inline("2.0") }}

Updates the most recent entry on the history stack to have the specified data, title, and, if provided, URL. The data is treated as opaque by the DOM; you may specify any JavaScript object that can be serialized.  Note that Firefox currently ignores the title parameter; for more information, see manipulating the browser history.

Note: In Gecko 2.0 {{ geckoRelease("2.0") }} through Gecko 5.0 {{ geckoRelease("5.0") }}, the passed object is serialized using JSON. Starting in Gecko 6.0 {{ geckoRelease("6.0") }}, the object is serialized using the structured clone algorithm. This allows a wider variety of objects to be safely passed.
No return value

See Manipulating the browser history for examples and details. In particular, that article explains security features of the pushState() and replaceState() methods that you should be aware of before using them.

The History object also has the following properties:

Property Type Description
length Integer Read-only. Returns the number of elements in the session history, including the currently loaded page. For example, for a page loaded in a new tab this property returns 1.
current {{ non-standard_inline() }} String Returns the URL of the active item of the session history. This property is not available to web content and is not supported by other browsers. Use location.href instead.
next {{ non-standard_inline() }} String Returns the URL of the next item in the session history. This property is not available to web content and is not supported by other browsers.
previous {{ non-standard_inline() }} String Returns the URL of the previous item in the session history. This property is not available to web content and is not supported by other browsers.
state {{ gecko_minversion_inline("2.0") }} {{ interface("nsIVariant") }}

Returns the state at the top of the history stack. This is a way to look at the state without having to wait for a popstate event. Read only.

Example

history.back();     // equivalent to clicking back button
history.go(-1);     // equivalent to history.back();

Notes

For top-level pages you can see the list of pages in the session history, accessible via the History object, in the browser's dropdowns next to the back and forward buttons.

For security reasons the History object doesn't allow the non-privileged code to access the URLs of other pages in the session history, but it does allow it to navigate the session history.

There is no way to clear the session history or to disable the back/forward navigation from unprivileged code. The closest available solution is the location.replace() method, which replaces the current item of the session history with the provided URL.

See also

{{ MSDN("ms535864", "history Object (window)") }}

Specification

{{ languages( { "ja": "ja/DOM/window.history" } ) }}

Revision Source

<p>{{ DomRef() }}</p>
<p>{{ DevDerbyPromoHeader("the History API") }}</p>
<h3 name="Summary">Summary</h3>
<p>Returns a reference to the <code>History</code> object, which provides an interface for manipulating the browser <em>session history</em> (pages visited in the tab or frame that the current page is loaded in).</p>
<h3 name="Syntax">Syntax</h3>
<pre class="eval"><em>var historyObj</em> = <em>window</em>.history;
</pre>
<p>The obtained <code>History</code> object has the following methods:</p>
<table class="fullwidth-table"> <tbody> <tr> <th>Method</th> <th>Description</th> <th>Return value</th> </tr> <tr> <td><code id="back">history.back()</code></td> <td> <p>Goes to the previous page in session history, the same action as when the user clicks the browser's Back button. Equivalent to <code>history.go(-1)</code>.</p> <div class="note"><strong>Note:</strong> Calling this method to go back beyond the first page in the session history has no effect and doesn't raise an exception.</div> </td> <td>No return value</td> </tr> <tr> <td><code id="forward">history.forward()</code></td> <td> <p>Goes to the next page in session history, the same action as when the user clicks the browser's Forward button; this is equivalent to <code>history.go(1)</code>.</p> <div class="note"><strong>Note:</strong> Calling this method to go back beyond the last page in the session history has no effect and doesn't raise an exception.</div> </td> <td>No return value</td> </tr> <tr> <td><code id="go">history.go(<em>integerDelta</em>)</code></td> <td>Loads a page from the session history, identified by its relative location to the current page, for example <code>-1</code> for the previous page or <code>1</code> for the next page. When <code><em>integerDelta</em></code> is out of bounds (e.g. -1 when there are no previously visited pages in the session history), the method doesn't do anything and doesn't raise an exception. Calling <code>go()</code> without parameters or with a non-integer argument has no effect (unlike Internet Explorer, <a class=" external" href="http://msdn.microsoft.com/en-us/library/ms536443(VS.85).aspx" title="http://msdn.microsoft.com/en-us/library/ms536443(VS.85).aspx">which supports string URLs as the argument</a>).</td> <td>No return value</td> </tr> <tr> <td><code>history.pushState(<em>data</em>, <em>title</em> [, <em>url</em>])</code> {{ gecko_minversion_inline("2.0") }}</td> <td> <p>Pushes the given data onto the session history stack with the specified title and, if provided, URL. The data is treated as opaque by the DOM; you may specify any JavaScript object that can be serialized.  Note that Firefox currently ignores the title parameter; for more information, see <a href="/en/DOM/Manipulating_the_browser_history" title="en/DOM/Manipulating the browser history">manipulating the browser history</a>.</p> <div class="note"><strong>Note:</strong> In Gecko 2.0 {{ geckoRelease("2.0") }} through Gecko 5.0 {{ geckoRelease("5.0") }}, the passed object is serialized using JSON. Starting in Gecko 6.0 {{ geckoRelease("6.0") }}, the object is serialized using <a href="/en/DOM/The_structured_clone_algorithm" title="en/DOM/The structured clone algorithm">the structured clone algorithm</a>. This allows a wider variety of objects to be safely passed.</div> </td> <td>No return value</td> </tr> <tr> <td><code>history.replaceState(<em>data</em>, <em>title</em> [, <em>url</em>]) </code>{{ gecko_minversion_inline("2.0") }}</td> <td> <p>Updates the most recent entry on the history stack to have the specified data, title, and, if provided, URL. The data is treated as opaque by the DOM; you may specify any JavaScript object that can be serialized.  Note that Firefox currently ignores the title parameter; for more information, see <a href="/en/DOM/Manipulating_the_browser_history" title="en/DOM/Manipulating the browser history">manipulating the browser history</a>.</p> <div class="note"><strong>Note:</strong> In Gecko 2.0 {{ geckoRelease("2.0") }} through Gecko 5.0 {{ geckoRelease("5.0") }}, the passed object is serialized using JSON. Starting in Gecko 6.0 {{ geckoRelease("6.0") }}, the object is serialized using <a href="/en/DOM/The_structured_clone_algorithm" title="en/DOM/The structured clone algorithm">the structured clone algorithm</a>. This allows a wider variety of objects to be safely passed.</div> </td> <td>No return value</td> </tr> </tbody>
</table>
<p>See <a href="/en/DOM/Manipulating_the_browser_history" title="en/DOM/Manipulating the browser history">Manipulating the browser history</a> for examples and details. In particular, that article explains security features of the <code>pushState()</code> and <code>replaceState()</code> methods that you should be aware of before using them.</p>
<p>The <code>History</code> object also has the following properties:</p>
<table class="fullwidth-table"> <tbody> <tr> <th>Property</th> <th>Type</th> <th>Description</th> </tr> <tr> <td><code id="length">length</code></td> <td>Integer</td> <td>Read-only. Returns the number of elements in the session history, including the currently loaded page. For example, for a page loaded in a new tab this property returns <code>1</code>.</td> </tr> <tr> <td><code id="current">current</code> {{ non-standard_inline() }}</td> <td>String</td> <td>Returns the URL of the active item of the session history. This property is not available to web content and is not supported by other browsers. Use <code><a href="/en/DOM/window.location" title="en/DOM/window.location">location.href</a></code> instead.</td> </tr> <tr> <td><code id="next">next</code> {{ non-standard_inline() }}</td> <td>String</td> <td>Returns the URL of the next item in the session history. This property is not available to web content and is not supported by other browsers.</td> </tr> <tr> <td><code id="previous">previous</code> {{ non-standard_inline() }}</td> <td>String</td> <td>Returns the URL of the previous item in the session history. This property is not available to web content and is not supported by other browsers.</td> </tr> <tr> <td><code>state</code> {{ gecko_minversion_inline("2.0") }}</td> <td>{{ interface("nsIVariant") }}</td> <td> <p>Returns the state at the top of the history stack. This is a way to look at the state without having to wait for a <code>popstate</code> event. <strong>Read only.</strong></p> </td> </tr> </tbody>
</table>
<h3 name="Example">Example</h3>
<pre class="eval">history.back();     // equivalent to clicking back button
history.go(-1);     // equivalent to history.back();
</pre>
<h3 name="Notes">Notes</h3>
<p>For top-level pages you can see the list of pages in the session history, accessible via the <code>History</code> object, in the browser's dropdowns next to the back and forward buttons.</p>
<p>For security reasons the <code>History</code> object doesn't allow the non-privileged code to access the URLs of other pages in the session history, but it does allow it to navigate the session history.</p>
<p>There is no way to clear the session history or to disable the back/forward navigation from unprivileged code. The closest available solution is the <code><a href="/en/DOM/window.location#replace" title="en/DOM/window.location#replace">location.replace()</a></code> method, which replaces the current item of the session history with the provided URL.</p>
<h3 name="See_also">See also</h3>
<p>{{ MSDN("ms535864", "history Object (window)") }}</p>
<h3 name="Specification">Specification</h3>
<ul> <li><a class=" external" href="http://whatwg.org/html#the-history-interface">HTML5 History interface</a></li>
</ul>
<p>{{ languages( { "ja": "ja/DOM/window.history" } ) }}</p>
Revert to this revision