pushState en replaceState

Het eerste argument bestaat uit willekeurige serialiseerbare gegevens die aan de vermelding zijn gekoppeld. Lees deze later terug via history.state of in popstate-events. Gebruik dit om gebruikersinterface-status door te geven (welk tabblad geopend was, de scrollpositie), zodat terugnavigeren exact dezelfde weergave kan herstellen.

Het tweede argument is de titel van het geschiedenisitem. In de praktijk negeren alle moderne browsers dit — stel document.title = "..." rechtstreeks in om de titel te wijzigen. Geef uit conventie een lege tekenreeks door; dit heeft geen effect.

Het derde argument is de nieuwe URL. Relatieve URL's worden opgelost ten opzichte van de huidige pagina; de nieuwe URL moet dezelfde oorsprong hebben (een andere oorsprong veroorzaakt een SecurityError). Browsers halen de URL niet op — pushState werkt alleen de adresbalk en de geschiedenis bij.

history.replaceState(state, "", url) vervangt het huidige geschiedenisitem in plaats van een nieuw item toe te voegen. Gebruik dit wanneer je de URL wilt bijwerken zonder een nieuwe stap voor achteruitnavigatie te maken, bijvoorbeeld bij het bijwerken van een filterqueryreeks.

Wijzigingen van SPA-routes, zoals op een navigatielink klikken zonder de pagina volledig opnieuw te laden, een modaal venster openen zodat de knop voor terugnavigatie het venster sluit, en stappen in een wizard doorlopen. Elke betekenisvolle status moet een nieuw geschiedenisitem zijn, zodat de knop voor terugnavigatie doet wat gebruikers verwachten.

Updates van filters, sortering en paginering die de geschiedenis niet moeten vervuilen, doorsturen na het gedeeltelijk invullen van een formulier, en trackingparameters bijwerken zonder navigeerbare items te maken. Als de gebruiker op de knop voor terugnavigatie drukt, worden deze "tussenliggende" statussen overgeslagen.

pushState wijzigt alleen de URL — je code moet de DOM afzonderlijk bijwerken. Het patroon is: nieuwe inhoud weergeven en daarna pushState aanroepen. Samen zorgen die twee voor de SPA-ervaring.

Werk na navigatie document.title en metatags met og:title bij, zodat delen op sociale media en titels van browsertabbladen de huidige weergave weerspiegelen. Als je dit vergeet, blijft bij volgende deelacties de oorspronkelijke titel staan — een subtiele maar veelvoorkomende SPA-fout.

Als je pushState aanroept voordat de gebruiker heeft genavigeerd, overschrijf je het eerste geschiedenisitem. Gebruik replaceState om status aan het eerste geschiedenisitem van de pagina te koppelen — zo voeg je de status toe zonder de diepte van de geschiedenis te wijzigen.

URL's voor pushState moeten dezelfde oorsprong hebben. Als je pushState probeert aan te roepen voor https://evil.com, veroorzaakt dit een SecurityError. Zo wordt voorkomen dat pagina's de adresbalk vervalsen, zodat gebruikers denken dat ze op een andere website zijn.

pushState voegt een nieuw geschiedenisitem toe zonder de pagina opnieuw te laden — de basis van SPA-routering. replaceState werkt het huidige item op zijn plaats bij voor cosmetische URL-wijzigingen. Voor beide zijn URL's met dezelfde oorsprong vereist en het argument title wordt genegeerd. Werk de DOM altijd afzonderlijk bij en vergeet niet om document.title en metatags na navigatie bij te werken.