What is the History web API?

The web keeps growing and getting more sophisticated. Due to this, more support is being poured into the web, giving it the ability to do things native to the operating system.

Such support includes the History API.

History API

This API is used to manage or manipulate the history of our browser. It enables us to change the URL address in the browser address bar, and navigate back and forth in our browser history.

Whenever we navigate to a page, the URL of the page is added to the history stack. If we move to https://example.com and then move to https://example.com/page1, the history stack will look like this:

    History stack
-----------------------------
    1 "https://example.com"
    2 "https://example.com/page1"

The current page is https://example.com/page1. If we press the back button on our browser, the https://example.com will be loaded.

Then, if we press the forward button, https://example.com/page1 will be loaded.

You can see that the browser uses the history stack to load the previous and next web pages visited. The History API gives us the ability to move back and forth within the history stack.

The History API is in the window object:

    >> window.history

    // or just

    >> history

    <- > History { length: 0, scrollRestoration: "auto", state: {…} }

It returns a History object and inherits some methods from the HistoryPrototype class.

The most useful methods are:

• pushState
• replaceState
• back
• forward
• go()

pushState

This method pushes a new URL to the address bar and the history stack. This will cause the browser to load the URL in the current tab.

Syntax

Its general structure is like this:

pushState(stateObject, title, url)

Parameters

• The stateObject parameter is the data that will be passed to history event handlers when a new URL is pushed or popped from the history stack. The stateObject can contain any data you want.

• title is ignored by most browsers.

• url is the URL that will be pushed to the history stack. This URL in the address bar will change to this URL.

Example

If we have our history stack like this:

        1. example.com

Then, this will push example.com/page1 onto the history stack.

pushState(null, null, "example.com/page1")

The history stack will now look like this:

    1. example.com/page1
    2. example.com

replaceState

This replaces the current URL in the history stack with a new URL.

Syntax

Its general structure is this:

replaceState(stateObject, title, url)

Parameters

The parameters are the same as in the pushState method.

The current URL in the history stack will be set to this stateObject, title, and url.

Example

Let’s say we have a URL pushed to the stack by pushState:

pushState("someState", "title", "example.com")

The history stack looks like this:

1. "example.com" "someState" "title"

Then, we call this:

replaceState("currState", "currTitle", "example.com/page1")

This will replace the URL in the history state with the parameters passed to replaceState.

The history stack will now look like this:

1. "example.com/page1" "currState" "currTitle"

The current element in the history stack is the URL in the top position.

back

This method navigates to the previous URL from the current URL in the history stack.

Syntax

Its general structure is this:

history.back()

Parameters

This method does not take any input parameters.

Example

Let’s say our history stack looks like this:

    1. example.com
    2. example.com/page1
    3. example.com/page2

The current element in the history stack is example.com. If we call history.back(), the previous element, it is 2. example.com/page1 will be loaded in the browser.

If we call back() again, then the URL at 3, example.com/page2, will be loaded in the browser.

forward

This moves forward to the next URL in the history stack.

Syntax

Its general structure is this:

history.forward()

Parameters

This method takes no input parameters.

Example

Let’s say the history stack looks like this:

    1. example.com
    2. example.com/page1
    3. example.com/page2

Our current URL is example.com. If we move back down the stack twice, we will land at 3, example.com/page2.

Now, from 3, if we call history.forward(), we will move to 2, i.e., example.com/page1, and the browser will load it. If we call history.forward() again, we will move forward to 1, which is example.com.

go()

This method enables us to specify the index in the history stack we want to navigate to.

Syntax

Its general structure is this:

history.go(index)

Parameters

The index denotes the index in the history stack we want to move to.

Example

Let’s say we have this:

    History stack

    1. example.com
    2. example.com/page1
    3. example.com/page2

If we call history.go(2), the URL at 2, example.com/page1, will be loaded.

history.go(3) will load example.com/page2.

history.go(1) will load example.com.

If the index is 0 or no index was passed, the browser will reload the tab.

If the index is a negative number, e.g., go(-2) or go(), we will move backward in the history stack. In other words, history.back() is called.