HTML5 History API: "popstate" not called when navigating back from another page

Question

I have to maintain a site with an AJAX search form (for lets say books) and I want the search results to be a part of the browser history.

So I set the "popstate" event handler

window.addEventListener('popstate', function(e) {
    alert("popstate: " + JSON.stringify(e.state));
});

and call pushState() upon the successfull AJAX request:

var stateObj = { q: "harry potter" };
window.history.pushState(stateObj, "Result", "/search");

Then my clickflow is:

1. Load the page with the search form - NORMAL request - path is /
2. Enter a query string and submit the form - AJAX request - path changes to /search
3. Click on a search result - NORMAL request - path changes to /books/harry-potter

---

4. When I now go back by clicking the browser back button I would expect the "popstate" event to be triggered with the according state object. But nothing happens. - path changes to /search

---

5. When I then go back one more time I get an alert with popstate: null - path changes to /

6. And when I go forward after that, I get popstate: {"q":"harry potter"} - path changes to /search

---

So, the important popstate event (the one with the query string) gets only triggered when going forward, but not when going back.

Is this because im navigating back from a site, whose history entry has been created automatically instead of programmatically by pushState? But if so, the History API would only make sense for complete single page applications.

Behaviour is the same in any browser. Hope you can help me out :)

Answer 1

For anyone wanting a little more explanation as to why the popstate event only occurs in certain scenarios, this helped me:

On the MDN popstate event page it states:

A popstate event is dispatched to the window each time the active history entry changes between two history entries for the same document.

and

The popstate event is only triggered by performing a browser action, such as clicking on the back button (or calling history.back() in JavaScript), when navigating between two history entries for the same document.

So it looks like popstate is only called when navigating to different urls within the same document. This works great for SPAs but not for anything else.

As an additional note, the html5 spec for session history doesn't seem to have much clarity as to when the popstate event is called:

The popstate event is fired in certain cases when navigating to a session history entry.

Which may indicate that different browsers will treat it differently.

I would love more insight from anyone else

Answer 2

There's at least one way to make it work, based on this excerpt from Mozilla's Working with the history API:

... When the page reloads, the page will receive an onload event, but no popstate event. However, if you read the history.state property, you'll get back the state object you would have gotten if a popstate had fired.

A minimal working example can be found in the snippet below.

Run the code snippet and follow these steps to see it in action:

1. click "populate" to add some text to the display, dynamically (basically mock AJAX)
2. click "away" to navigate to example.org (don't worry, this happens inside the iframe)
3. click the browser's "back" button: the display is restored to its populated state
4. click browser "back" again to clear the display (initial empty state)

const populate = document.getElementById('populate');
const display = document.getElementById('display');

// connect the button
populate.addEventListener('click', () => {
  const state = 'hit browser back button to clear';
  updateDisplay(state);
  // push state onto history stack
  history.pushState(state, '', '#populated');
});

// listen for popstate event, fired e.g. after using browser back button
window.addEventListener('popstate', (event) => updateDisplay(event.state));

// listen for load event, in case we navigate away and then go back
window.addEventListener('load', () => updateDisplay(history.state), false);

function updateDisplay(state) {
  if (state) {
    display.textContent = state;
  } else {
    display.textContent = '';
  }
}

/* the styling is only cosmetic */

.button {
  text-decoration: underline;
  cursor: pointer;
  color: blue;
}

<div class="button" id="populate">populate</div>
<a class="button" href="https://example.org">away</a>
<div id="display"></div>

As noted here:

The state object can be anything that can be serialized.