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.
Navigating the History
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