The History API is a set of browser features that allow developers to interact with the address bar and navigation history. It is especially useful for modern Single Page Applications that rely on client-side rendering and dynamic content updates.

Accessing the History API

To access the History API, you can simply use the window.history object. It is also possible to use the history object directly, as window is the global object.

The History API provides methods to navigate through the browser history. The history.back() method allows you to go back to the previous page, just like clicking the browser’s back button. Similarly, the history.forward() method lets you move forward to the next page in the history.

The history.go() method allows for more granular navigation. It takes an integer as an argument, indicating the number of steps to go back or forward in the history. For example, history.go(-1) is equivalent to history.back(), and history.go(1) is equivalent to history.forward(). You can also navigate multiple steps at once, such as history.go(-2) or history.go(3).

Additionally, you can check the number of entries in the history by accessing the history.length property.

Adding an Entry to the History

Using the pushState() method, you can programmatically add a new entry to the browser history. It takes three parameters: a state object, a title (usually an empty string), and a URL associated with the new state. The URL must belong to the same origin domain as the current URL.

For example, the following code creates a new history entry with a state object and an associated URL:

const state = { name: 'Flavio' }
history.pushState(state, '', '/user')

Note that calling pushState() does not change the content of the page or trigger any browser action like changing window.location would.

Modifying History Entries

While pushState() adds a new state to the history, the replaceState() method allows you to edit the current history state. It takes the same three parameters as pushState(), but differentiates itself by replacing the current state instead of adding a new one.

For example, the following code replaces the current history state with a new state object and updates the associated URL:

history.pushState({}, '', '/posts')
const state = { post: 'first' }
history.pushState(state, '', '/post/first')
const state = { post: 'second' }
history.replaceState(state, '', '/post/second')

If you then call history.back(), the browser will navigate to /posts as the previous state /post/first has been replaced by /post/second.

Accessing the Current History Entry State

To access the current history entry state, simply access the history.state property. This property returns the state object that was passed to pushState() or replaceState().

The onpopstate Event

The onpopstate event is triggered on the window object whenever the active history state changes. The event handler receives the current state as a parameter.

For example, you can listen for the onpopstate event and log the state object whenever the user navigates through the history using the back, forward, or go methods:

window.onpopstate = event => {
 console.log(event.state)
}

Tags:

History API, browser history, navigation history, Single Page Applications, window.history, history.back(), history.forward(), history.go(), history.length, pushState(), replaceState(), history.state, onpopstate event