JS History

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

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

Note: Note! To protect user privacy, there are limitations to how JavaScript can access the history object. For privacy reasons, JavaScript cannot read the URLs stored in the browser history.

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

<button onclick="window.history.back()">Go Back</button>

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

<button onclick="history.forward()">Go Forward</button>

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

<button onclick="history.go(-2)">Go Back</button>

Example

<button onclick="history.go(1)">Go Forward</button>

Note: Negative numbers move backward. Positive numbers move forward. history.go(0) reloads the current page. history.back() is equivalent to history.go(-1). history.forward() is equivalent to history.go(1).

The history.length Property

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

Examples

let length = window.history.length;

Note: The current page is included in the number.

The history.state Property

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

Example

let state = history.state;

Note: The value of history.state is null until you call history.pushState() or history.replaceState().

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.

Note: Does Not Load a New Page The history.pushState() method does not load a new page. It adds a new entry to the browser history, including the URL and the state object. If the page content should change, JavaScript must change it separately with a statemet like location.href = "page2.html";

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)

Note: Does Not Load a New Page The history.replaceState() method does not load a new page. It changes the current history entry, including the URL and the state object. If the page content should change, JavaScript must change it separately with a statemet like location.href = "page2.html";

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);

  }

});

Note: Calling pushState() or replaceState() does not trigger a popstate event.

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

<button onclick="showPage('home')">Home</button>

<button onclick="showPage('about')">About</button>

<p id="demo">Home</p>

<script>

function showPage(page) {

  myDisplayer(page);

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

}

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

  if (event.state) {

    myDisplayer(event.state.page);

  }

});

</script>

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