History: pushState() method section-content is confusing

[zjlovezj]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/History/pushState

What specific section or headline is this issue about?

section-content

What information was incorrect, unhelpful, or incomplete?

This method is asynchronous. Add a listener for the popstate event in order to determine when the navigation has completed. The state parameter will be available in it.

What did you expect to see?

This method is asynchronous. sort of implies that the popstate event listener got a event when history.push has resolved.

And how do the user know when history.push has resolved? Or maybe it doesn't matter.

popstate event may never fired as popstate described.

I think it should made clear that history.push trigger no events, correct me if I'm wrong.

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

From blank page to abc.html, abc.html includes below js

history.pushState({a: 1}, '');
history.pushState({a: 2}, '');

If pushState without change url, at least in Chrome,

1. click browser Back button will go back to the blank page
2. do history.back() will stay at the abc.html and trigger a popstate event

Maybe this behavior worth a notice.

MDN metadata

Page report details

• Folder: en-us/web/api/history/pushstate
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/History/pushState
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/api/history/pushstate/index.md
• Last commit: ab8736c
• Document last modified: 2023-09-27T04:57:54.000Z

[wbamberg]

I'm not very familiar with this API and our docs on it (especially the guide) are very confusing, but yes, this looks like a mistake to me. pushState() doesn't cause a navigation, it just adds an entry to the history. So "when the navigation has completed" is not connected to pushState() completing, right?

This paragraph was added in #25702, to match some APIs like forward() that do cause a navigation. I wonder if this was an error - @teoli2003 do you know?