JavaScript History : Object

Represents the history of pages displayed to the user. Allows the webpage to manipulate the history by adding new pages or navigating between pages already in the history. Use the window.onpopstate event to listen to the user changing the page through the browser's back/forward buttons. See also Location.

Spec

Instance Properties

length : Number readonly

The number of items in the browser session's history.

Example:

<button onclick='pushState()'>Push State</button><br>
<button onclick='replaceState()'>Replace State</button><br>
<button onclick='history.back()'>Back</button><br>
<button onclick='history.forward()'>Forward</button><br>
<input id='goAmount' value='-1'><button onclick='go()'>Go</button>
<div>
  history.state = <span id='historyState'></span>
</div>
<div>
  history.length = <span id='historyLength'></span>
</div>
<div>
  href = <span id='locationHref'></span>
</div>
<script>
  var onStateChange = function() {
    document.getElementById('historyState').textContent = history.state;
    document.getElementById('historyLength').textContent = history.length;
    document.getElementById('locationHref').textContent = location.href;
  };

  window.onpopstate = onStateChange;

  onStateChange();

  var pushState = function() {
    var newState = (history.state || 0) + 1;
    history.pushState(newState, 'Pushed: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var replaceState = function() {
    var newState = (history.state || 0) + 1;
    history.replaceState(newState, 'Replaced: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var go = function() {
    var amount = +document.getElementById('goAmount').value;
    history.go(amount);
  };
</script>

Run

Results:

Spec

state : Object readonly

The data passed to pushState() or replaceState() for the current page.

Example:

<button onclick='pushState()'>Push State</button><br>
<button onclick='replaceState()'>Replace State</button><br>
<button onclick='history.back()'>Back</button><br>
<button onclick='history.forward()'>Forward</button><br>
<input id='goAmount' value='-1'><button onclick='go()'>Go</button>
<div>
  history.state = <span id='historyState'></span>
</div>
<div>
  history.length = <span id='historyLength'></span>
</div>
<div>
  href = <span id='locationHref'></span>
</div>
<script>
  var onStateChange = function() {
    document.getElementById('historyState').textContent = history.state;
    document.getElementById('historyLength').textContent = history.length;
    document.getElementById('locationHref').textContent = location.href;
  };

  window.onpopstate = onStateChange;

  onStateChange();

  var pushState = function() {
    var newState = (history.state || 0) + 1;
    history.pushState(newState, 'Pushed: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var replaceState = function() {
    var newState = (history.state || 0) + 1;
    history.replaceState(newState, 'Replaced: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var go = function() {
    var amount = +document.getElementById('goAmount').value;
    history.go(amount);
  };
</script>

Run

Results:

Spec

Instance Methods

back() : undefined

Navigates back one page in the session history. Equivalent to go(-1).

Example:

<button onclick='pushState()'>Push State</button><br>
<button onclick='replaceState()'>Replace State</button><br>
<button onclick='history.back()'>Back</button><br>
<button onclick='history.forward()'>Forward</button><br>
<input id='goAmount' value='-1'><button onclick='go()'>Go</button>
<div>
  history.state = <span id='historyState'></span>
</div>
<div>
  history.length = <span id='historyLength'></span>
</div>
<div>
  href = <span id='locationHref'></span>
</div>
<script>
  var onStateChange = function() {
    document.getElementById('historyState').textContent = history.state;
    document.getElementById('historyLength').textContent = history.length;
    document.getElementById('locationHref').textContent = location.href;
  };

  window.onpopstate = onStateChange;

  onStateChange();

  var pushState = function() {
    var newState = (history.state || 0) + 1;
    history.pushState(newState, 'Pushed: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var replaceState = function() {
    var newState = (history.state || 0) + 1;
    history.replaceState(newState, 'Replaced: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var go = function() {
    var amount = +document.getElementById('goAmount').value;
    history.go(amount);
  };
</script>

Run

Results:

Spec

forward() : undefined

Navigates forward one page in the session history. Equivalent to go(1).

Example:

<button onclick='pushState()'>Push State</button><br>
<button onclick='replaceState()'>Replace State</button><br>
<button onclick='history.back()'>Back</button><br>
<button onclick='history.forward()'>Forward</button><br>
<input id='goAmount' value='-1'><button onclick='go()'>Go</button>
<div>
  history.state = <span id='historyState'></span>
</div>
<div>
  history.length = <span id='historyLength'></span>
</div>
<div>
  href = <span id='locationHref'></span>
</div>
<script>
  var onStateChange = function() {
    document.getElementById('historyState').textContent = history.state;
    document.getElementById('historyLength').textContent = history.length;
    document.getElementById('locationHref').textContent = location.href;
  };

  window.onpopstate = onStateChange;

  onStateChange();

  var pushState = function() {
    var newState = (history.state || 0) + 1;
    history.pushState(newState, 'Pushed: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var replaceState = function() {
    var newState = (history.state || 0) + 1;
    history.replaceState(newState, 'Replaced: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var go = function() {
    var amount = +document.getElementById('goAmount').value;
    history.go(amount);
  };
</script>

Run

Results:

Spec

go([delta : Number]) : undefined

Navigates through the session history by the specified amount. If delta is not provided, go() acts the same as location.reload() and reloads the current page. See also back() and forward().

Example:

<button onclick='pushState()'>Push State</button><br>
<button onclick='replaceState()'>Replace State</button><br>
<button onclick='history.back()'>Back</button><br>
<button onclick='history.forward()'>Forward</button><br>
<input id='goAmount' value='-1'><button onclick='go()'>Go</button>
<div>
  history.state = <span id='historyState'></span>
</div>
<div>
  history.length = <span id='historyLength'></span>
</div>
<div>
  href = <span id='locationHref'></span>
</div>
<script>
  var onStateChange = function() {
    document.getElementById('historyState').textContent = history.state;
    document.getElementById('historyLength').textContent = history.length;
    document.getElementById('locationHref').textContent = location.href;
  };

  window.onpopstate = onStateChange;

  onStateChange();

  var pushState = function() {
    var newState = (history.state || 0) + 1;
    history.pushState(newState, 'Pushed: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var replaceState = function() {
    var newState = (history.state || 0) + 1;
    history.replaceState(newState, 'Replaced: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var go = function() {
    var amount = +document.getElementById('goAmount').value;
    history.go(amount);
  };
</script>

Run

Results:

Spec

pushState(state : Object, title : String, [url : String]) : undefined

Adds a new entry to the session history. state is available on the history.state property. title is applied to document.title. If url is specified, the location.href is changed to the provided value.

Example:

<button onclick='pushState()'>Push State</button><br>
<button onclick='replaceState()'>Replace State</button><br>
<button onclick='history.back()'>Back</button><br>
<button onclick='history.forward()'>Forward</button><br>
<input id='goAmount' value='-1'><button onclick='go()'>Go</button>
<div>
  history.state = <span id='historyState'></span>
</div>
<div>
  history.length = <span id='historyLength'></span>
</div>
<div>
  href = <span id='locationHref'></span>
</div>
<script>
  var onStateChange = function() {
    document.getElementById('historyState').textContent = history.state;
    document.getElementById('historyLength').textContent = history.length;
    document.getElementById('locationHref').textContent = location.href;
  };

  window.onpopstate = onStateChange;

  onStateChange();

  var pushState = function() {
    var newState = (history.state || 0) + 1;
    history.pushState(newState, 'Pushed: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var replaceState = function() {
    var newState = (history.state || 0) + 1;
    history.replaceState(newState, 'Replaced: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var go = function() {
    var amount = +document.getElementById('goAmount').value;
    history.go(amount);
  };
</script>

Run

Results:

Spec

replaceState(state : Object, title : String, [url : String]) : undefined

Replaces the current entry in the session history with the provided values. state is available on the history.state property. title is applied to document.title. If url is specified, the location.href is changed to the provided value.

Example:

<button onclick='pushState()'>Push State</button><br>
<button onclick='replaceState()'>Replace State</button><br>
<button onclick='history.back()'>Back</button><br>
<button onclick='history.forward()'>Forward</button><br>
<input id='goAmount' value='-1'><button onclick='go()'>Go</button>
<div>
  history.state = <span id='historyState'></span>
</div>
<div>
  history.length = <span id='historyLength'></span>
</div>
<div>
  href = <span id='locationHref'></span>
</div>
<script>
  var onStateChange = function() {
    document.getElementById('historyState').textContent = history.state;
    document.getElementById('historyLength').textContent = history.length;
    document.getElementById('locationHref').textContent = location.href;
  };

  window.onpopstate = onStateChange;

  onStateChange();

  var pushState = function() {
    var newState = (history.state || 0) + 1;
    history.pushState(newState, 'Pushed: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var replaceState = function() {
    var newState = (history.state || 0) + 1;
    history.replaceState(newState, 'Replaced: ' + newState, '/History?state=' + newState);
    onStateChange();
  };

  var go = function() {
    var amount = +document.getElementById('goAmount').value;
    history.go(amount);
  };
</script>

Run

Results:

Spec

home license contribute feedback