pushState e replaceState

A API History permite que uma página altere a URL exibida na barra de endereços sem iniciar uma navegação completa. Combinada à renderização no lado do cliente, ela possibilita criar Aplicações de página única com aparência nativa, sem abrir mão de URLs que podem ser adicionadas aos favoritos.

history.pushState(state, "", url) adiciona uma nova entrada ao histórico do navegador. A URL na barra de endereços é atualizada imediatamente; nenhuma solicitação de rede é feita. O usuário pode voltar à entrada anterior usando o botão Voltar do navegador.

O primeiro argumento é formado por dados serializáveis arbitrários anexados à entrada. Leia-os posteriormente por meio de history.state ou em eventos popstate. Use esse argumento para passar o estado da interface (qual aba estava aberta ou a posição da rolagem), permitindo que a navegação de retorno restaure exatamente a visualização anterior.

O segundo argumento é o título da entrada. Na prática, todos os navegadores modernos o ignoram — defina document.title = "..." diretamente para alterar o título. Passe um valor vazio por convenção; isso não tem efeito.

O terceiro argumento é o novo endereço. Endereços relativos são resolvidos com base na página atual; o novo endereço deve ter a mesma origem (uma origem cruzada lança SecurityError). Os navegadores não buscam o endereço — pushState apenas atualiza a barra de endereço e o histórico.

history.replaceState(state, "", url) substitui a entrada atual do histórico em vez de adicionar uma nova. Use quando quiser atualizar o endereço sem criar um novo passo de navegação para trás (por exemplo, ao atualizar uma cadeia de consulta de filtro).

Alterações de rota na SPA (clicar em um link de navegação sem recarregar a página inteira), abertura de uma janela modal (para que o botão Voltar feche a janela), transições entre etapas de um assistente. Cada estado significativo deve ser uma nova entrada do histórico, para que o botão Voltar faça o que os usuários esperam.

Atualizações de filtros, ordenação e paginação que não devem encher o histórico, redirecionamento após a conclusão parcial de um formulário, atualização de parâmetros de rastreamento sem criar entradas navegáveis. Ao pressionar Voltar, o usuário ignora esses estados "intermediários".

pushState apenas altera o endereço — seu código deve atualizar o DOM separadamente. O padrão é: renderizar o novo conteúdo e depois chamar pushState. Juntos, os dois produzem a experiência de uma SPA.

Atualize document.title e os metadados de título depois da navegação, para que o compartilhamento em redes sociais e os títulos das abas do navegador reflitam a visualização atual. Esquecer isso deixa o título original nos compartilhamentos seguintes — um erro sutil, mas comum, em uma SPA.

Chamar pushState antes de o usuário navegar sobrescreve a entrada inicial. Para associar um estado à primeira entrada da página, use replaceState — isso adiciona o estado sem alterar a profundidade do histórico.

Os endereços usados por pushState devem ter a mesma origem. Tentar executar pushState com https://evil.com lança SecurityError. Isso impede que as páginas falsifiquem a barra de endereço para fazer os usuários pensarem que estão em outro site.

O que history.replaceState faz que history.pushState não faz?

pushState adiciona uma nova entrada ao histórico sem recarregar a página — a base do roteamento de SPA. replaceState atualiza a entrada atual no próprio lugar para alterações meramente visuais no endereço. Ambos exigem endereços com a mesma origem e ignoram o argumento de título. Sempre atualize o DOM separadamente e lembre-se de atualizar document.title e os metadados depois da navegação.