files/en-us/web/api/window/popstate_event/index.md
{{APIRef("History API")}}
The popstate event of the {{domxref("Window")}} interface is fired when the active history entry changes while the user navigates the session history. It changes the current history entry to that of the last page the user visited or, if {{domxref("history.pushState()")}} has been used to add a history entry to the history stack, that history entry is used instead.
Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
addEventListener("popstate", (event) => { })
onpopstate = (event) => { }
A {{domxref("PopStateEvent")}}. Inherits from {{domxref("Event")}}.
{{InheritanceDiagram("PopStateEvent")}}
pushState() or replaceState().In addition to the Window interface, the event handler property onpopstate is also available on the following elements:
If the history entry being activated was created by a call to history.pushState() or was affected by a call to history.replaceState(), the popstate event's state property contains a copy of the history entry's state object.
These methods and their corresponding events can be used to add data to the history stack which can be used to reconstruct a dynamically generated page, or to otherwise alter the state of the content being presented while remaining on the same {{domxref("Document")}}.
Note that just calling history.pushState() or history.replaceState() won't trigger a popstate event. The popstate event will be triggered by doing a browser action such as a click on the back or forward button (or calling history.back() or history.forward() in JavaScript).
[!NOTE] When writing functions that process
popstateevent it is important to take into account that properties likewindow.locationwill already reflect the state change (if it affected the current URL), butdocumentmight still not. If the goal is to catch the moment when the new document state is already fully in place, a zero-delay {{domxref("Window.setTimeout", "setTimeout()")}} method call should be used to effectively put its inner callback function that does the processing at the end of the browser event loop:window.onpopstate = () => setTimeout(doSomeThing, 0);
It's important to first understand that — to combat unwanted pop-ups — browsers may not fire the popstate event at all unless the page has been interacted with.
This section describes the steps that browsers follow in the cases where they do potentially fire the popstate event (that is, in the cases where the page has been interacted with).
When a navigation occurs — either due to the user triggering the browser's <kbd>Back</kbd> button or otherwise — the popstate event is near the end of the process to navigate to the new location. It happens after the new location has loaded (if needed), displayed, made visible, and so on — after the {{domxref("Window/pageshow_event", "pageshow")}} event is sent, but before the persisted user state information is restored and the {{domxref("Window/hashchange_event", "hashchange")}} event is sent.
To better understand when the popstate event is fired, consider this simplified sequence of events that occurs when the current history entry changes due to either the user navigating the site or the history being traversed programmatically. Here, the transition is changing the current history entry to one we'll refer to as new-entry. The current page's session history stack entry will be referred to as current-entry.
Document before continuing. This will eventually send events such as {{domxref("Document/DOMContentLoaded_event", "DOMContentLoaded")}} and {{domxref("Window/load_event", "load")}} to the {{domxref("Window")}} containing the document, but the steps below will continue to execute in the meantime.Document object than current-entry, the browsing context is updated so that its {{domxref("Window.document", "document")}} property refers to the document referred to by new-entry, and the context's name is updated to match the context name of the now-current document.autocomplete configured with its autofill field name set to off is reset. See The HTML autocomplete attribute for more about the autocomplete field names and how autocomplete works.complete—and the document is not already visible, it's made visible and the {{domxref("Window/pageshow_event", "pageshow")}} event is fired at the document with the {{domxref("PageTransitionEvent")}}'s {{domxref("PageTransitionEvent.persisted", "persisted")}} attribute set to true.delta parameter on methods such as {{domxref("History.go", "go()")}}) is removed from the history stack.null, the document is scrolled to that fragment.state is null.state changed, the popstate event is sent to the document.As you can see, the popstate event is nearly the last thing done in the process of navigating pages in this way.
A page at http://example.com/example.html running the following code will generate logs as indicated:
window.addEventListener("popstate", (event) => {
console.log(
`location: ${document.location}, state: ${JSON.stringify(event.state)}`,
);
});
history.pushState({ page: 1 }, "title 1", "?page=1");
history.pushState({ page: 2 }, "title 2", "?page=2");
history.replaceState({ page: 3 }, "title 3", "?page=3");
history.back(); // Logs "location: http://example.com/example.html?page=1, state: {"page":1}"
history.back(); // Logs "location: http://example.com/example.html, state: null"
history.go(2); // Logs "location: http://example.com/example.html?page=3, state: {"page":3}"
The same example using the onpopstate event handler property:
window.onpopstate = (event) => {
console.log(
`location: ${document.location}, state: ${JSON.stringify(event.state)}`,
);
};
history.pushState({ page: 1 }, "title 1", "?page=1");
history.pushState({ page: 2 }, "title 2", "?page=2");
history.replaceState({ page: 3 }, "title 3", "?page=3");
history.back(); // Logs "location: http://example.com/example.html?page=1, state: {"page":1}"
history.back(); // Logs "location: http://example.com/example.html, state: null"
history.go(2); // Logs "location: http://example.com/example.html?page=3, state: {"page":3}"
Note that even though the original history entry (for http://example.com/example.html) has no state object associated with it, a popstate event is still fired when we activate that entry after the second call to history.back().
{{Specifications}}
{{Compat}}