JavaScript History API
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 metods are:
history.back()- same as clicking back in the browserhistory.forward()- same as clicking forward in the browser
History Object Methods
| 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 |
| pushState() | Adds a new entry to the session history |
| replaceState() | Changes the current history entry |
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
| Property | Description |
|---|---|
| length | Returns the number of entries in the history |
| state | Returns the state of the current history entry |
| scrollRestoration | Gets or sets the scroll restoration behavior |
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="window.history.back()">Go Back</button>
Remember: The window prefix can be omitted:
<button onclick="history.back()">Go Back</button>
The output of the code above will be:
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 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.
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;
The window prefix can be omitted:
let length = history.length;
Try it Yourself »
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 entryhistory.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)
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.
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.
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)
Example
let state = {name:"example", page: 2};
let url = "page2.html";
history.replaceState(state, "", url);
Try it Yourself »
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>
Try it Yourself »
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
