`pushState` et `replaceState`

L’API History permet à une page de modifier l’URL affichée dans la barre d’adresse sans déclencher une navigation complète. Associée au rendu côté client, elle permet de créer des applications monopages qui semblent natives sans renoncer à des URL pouvant être ajoutées aux favoris.

history.pushState(state, "", url) ajoute une nouvelle entrée à l’historique du navigateur. L’URL de la barre d’adresse est mise à jour immédiatement ; aucune requête réseau n’est effectuée. L’utilisateur peut revenir à l’entrée précédente avec le bouton Retour du navigateur.

Le premier argument est une donnée sérialisable quelconque associée à l’entrée. Relisez-la plus tard via history.state ou dans les événements popstate. Utilisez-la pour transmettre l’état de l’interface (l’onglet ouvert, la position de défilement), afin que le retour en arrière puisse restaurer exactement la vue précédente.

Le deuxième argument est le titre de l’entrée. En pratique, tous les navigateurs modernes l’ignorent — définissez directement document.title = "..." pour modifier le titre. Par convention, transmettez une chaîne vide ; cela n’a aucun effet.

Le troisième argument est la nouvelle URL. Les URL relatives sont résolues par rapport à la page actuelle ; la nouvelle URL doit être de même origine (une URL d’une autre origine déclenche SecurityError). Les navigateurs ne récupèrent pas l’URL — pushState met uniquement à jour la barre d’adresse et l’historique.

history.replaceState(state, "", url) remplace l’entrée actuelle de l’historique au lieu d’en ajouter une nouvelle. Utilisez-le lorsque vous souhaitez mettre à jour l’URL sans créer une nouvelle étape de navigation arrière (par exemple, pour mettre à jour la chaîne de requête d’un filtre).

Changements de route d’une SPA (cliquer sur un lien de navigation sans rechargement complet), ouverture d’une fenêtre modale (afin que le bouton Retour ferme la fenêtre modale), transitions entre les étapes d’un assistant. Chaque état significatif doit être une nouvelle entrée de l’historique, afin que le bouton Retour se comporte comme les utilisateurs s’y attendent.

Mises à jour de filtres, de tris ou de pagination qui ne doivent pas encombrer l’historique, redirection après la complétion partielle d’un formulaire, mise à jour de paramètres de suivi sans créer d’entrées navigables. Lorsque l’utilisateur revient en arrière, ces états « intermédiaires » sont ignorés.

pushState ne modifie que l’URL — votre code doit mettre à jour le DOM séparément. Le principe est le suivant : afficher le nouveau contenu, puis appeler pushState. Ces deux opérations produisent ensemble l’expérience d’une SPA.

Mettez à jour document.title et les balises meta de titre Open Graph après la navigation afin que le partage sur les réseaux sociaux et les titres des onglets du navigateur reflètent la vue actuelle. Si vous l’oubliez, le titre d’origine reste présent lors des partages suivants — un défaut discret mais fréquent des SPA.

Appeler pushState avant toute navigation de l’utilisateur écrase l’entrée initiale. Pour associer un état à la première entrée de la page, utilisez replaceState — cela ajoute l’état sans modifier la profondeur de l’historique.

Les URL utilisées avec pushState doivent être de même origine. Tenter d’utiliser pushState avec https://evil.com déclenche SecurityError. Cela empêche les pages de falsifier la barre d’adresse pour faire croire aux utilisateurs qu’ils se trouvent sur un autre site.

Que fait history.replaceState contrairement à history.pushState ?

pushState ajoute une nouvelle entrée à l’historique sans recharger la page — c’est le fondement du routage des SPA. replaceState met à jour l’entrée actuelle sur place pour les changements d’URL d’ordre esthétique. Les deux exigent des URL de même origine et ignorent l’argument de titre. Mettez toujours à jour le DOM séparément et pensez à actualiser document.title et les balises meta après la navigation.