JavaScript History API

The History API lets you work with the browser's session history.

You can:

• Move backward
• Move forward
• Add new history entries
• Change the current entry

Share

The History Object

The History API is accessed with the window.history object.

The history object can be written without the window prefix.

The most common methods are:

• history.back() - same as clicking back in the browser
• history.forward() - same as clicking forward in the browser

History Object Methods

Use back(), forward(), and go() to navigate through the session history.

Use pushState() to create a new history entry without loading a new page.

Use replaceState() to change the current entry without loading a new page.

Use the popstate event to detect when the user moves to another history entry.

History Object Properties

The history.back() Method

The history.back() method loads the previous page in the session history.

This is the same as clicking the browser's Back button.

Example

**Go Back

The history.forward() Method

The history.forward() method loads the next page in the session history.

This is the same as clicking the browser's Forward button.

Example

**Go Forward

The history.go() Method

The history.go() method loads a specific page from the session history.

The argument tells the browser how many steps to move from the current page.

Example

Go Back

Example

Go Forward

The history.length Property

The history.length property returns the number of entries in the session history.

Examples

let length = window.history.length;

The history.state Property

The history.state property returns the state data associated with the current history entry.

Example

let state = history.state;

Changing the Browser History

The History API can also add or replace entries in the browser history.

This is useful for applications that change page content without loading a completely new document.

The two methods are:

• history.pushState() - adds a new history entry
• history.replaceState() - replaces the current history entry

The history.pushState() Method

The history.pushState() method adds a new entry to the session history.

Syntax

history.pushState(state, "", url)

The example changes the URL to page2.html and adds a new history entry.

It does not load page2.html from the server.

In the state argument you can store any data associated with the entry.

The second argument ("") exists for historical reasons and is normally empty.

The optional url argument must have the same origin as the current page.

The history.replaceState() Method

The history.replaceState() method changes the current history entry.

Unlike history.pushState(), it does not create a new history entry.

This changes the current URL without adding another entry to the browser history:

Syntax

history.replaceState(state, "", url)

The popstate Event

The popstate event occurs when the active history entry changes.

This normally happens when the user clicks the browser's Back or Forward button.

Example

window.addEventListener("popstate", function(event) {

  myDisplayer("Page changed");

});

If a history entry contains state data, it is available from event.state:

Example

window.addEventListener("popstate", function(event) {

  if (event.state) {

    myDisplayer(event.state.page);

  }

});

A Simple History API Example

The following example changes the URL without loading a new page.

It also restores the displayed content when the user clicks Back or Forward.

Example

**Home

 About

Home

function showPage(page) {

  myDisplayer(page);

  history.pushState({page: page}, "", "?page=" + page);

}

window.addEventListener("popstate", function(event) {

  if (event.state) {

    myDisplayer(event.state.page);

  }

});

Scroll Restoration

Browsers normally restore the scroll position when users move backward or forward.

The history.scrollRestoration property can control this behavior.

Example

history.scrollRestoration = "manual";

The possible values are:

• "auto" - the browser restores the scroll position
• "manual" - the application controls the scroll position