JavaScript History API
The JavaScript History API lets you work with the browser's session history.
The window.history object contains the browsers history.
You can move backward and forward, add new history entries, and change the current history entry.
The History Object
The History API is accessed with the window.history object.
The history object can be written without the window prefix.
Common metods are:
- history.back() - same as clicking back in the browser
- history.forward() - same as clicking forward in the browser
Examples
let length = window.history.length;
The window prefix can be omitted:
let length = history.length;
Try it Yourself »
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
history.back() loads the previous URL in the history list:
<button onclick="history.back()">Go Back</button>
The output of the code above will be:
The history.back() method is equivalent to history.go(-1).
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
history.forward() loads the next URL in the history list.
<button onclick="history.forward()">Go Forward</button>
The output of the code above will be:
The forward() method is equivalent to history.go(1).
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 two pages:
<button onclick="history.go(-2)">Go Back</button>
The output of the code above will be:
Example
Go forward one page:
<button onclick="history.go(1)">Go Forward</button>
The output of the code above will be:
Negative numbers move backward.
Positive numbers move forward.
history.go(0) reloads the current page.
The history.length Property
The history.length property returns the number of entries in the session history.
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.
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.
Example
let state = {name:"example", page: 2};
let url = "page2.html";
history.pushState(state, "", url);
Try it Yourself »
The example changes the URL to page2.html and adds a new history entry.
It does not load page2.html from the server.
Syntax
history.pushState(state, "", url)
A state object can store any data associated with the history entry.
The second argument exists for historical reasons and is normally an empty string.
The optional url must have the same origin as the current page.
history.state is null until you call history.pushState() or history.replaceState().
The history.replaceState() Method
The history.replaceState() method changes the current history entry.
Unlike pushState(), it does not create a new history entry.
Example
history.replaceState(null, "", "newpage.html");
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) {
document.getElementById("demo").innerHTML =
"Page changed";
});
If a history entry contains state data, it is available from event.state:
Example
window.addEventListener("popstate", function(event) {
if (event.state) {
document.getElementById("demo").innerHTML =
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) {
document.getElementById("demo").innerHTML = page;
history.pushState({page: page}, "", "?page=" + page);
}
window.addEventListener("popstate", function(event) {
if (event.state) {
document.getElementById("demo").innerHTML =
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
Disable automatic scroll restoration:
history.scrollRestoration = "manual";
The possible values are:
- "auto" - the browser restores the scroll position
- "manual" - the application controls the scroll position
History Object Reference
| Property / Method | Description |
|---|---|
| back() | Loads the previous entry in the session history |
| forward() | Loads the next entry in the session history |
| go() | Loads an entry relative to the current entry |
| length | Returns the number of entries in the session history |
| pushState() | Adds a new entry to the session history |
| replaceState() | Changes the current history entry |
| state | Returns the state data of the current history entry |
| scrollRestoration | Gets or sets the browser's scroll restoration behavior |
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 history entry.
Use the popstate event to detect when the user moves to another history entry.
