O evento popstate

O evento popstate é disparado na janela quando o usuário navega pelo histórico (para trás, para frente ou por meio de uma chamada JavaScript a history.back). Ele permite que a SPA renderize novamente a visualização correta em resposta à navegação iniciada pelo navegador.

O evento é disparado ao clicar nos botões Voltar e Avançar, ao chamar history.back(), history.forward() e history.go(n). Ele NÃO é disparado quando pushState/replaceState são chamados manualmente — essas são atualizações programáticas, e a página já tem conhecimento delas.

A propriedade state do evento contém o objeto de estado que você passou para pushState/replaceState referente à entrada para a qual a navegação foi feita. Use-a para restaurar o estado da interface (aba aberta, posição de rolagem) que não fica armazenado no endereço.

A barra de endereço já foi atualizada quando o evento é disparado. Leia location.pathname, location.search e location.hash para encontrar o novo endereço. Junto com o estado, essas são todas as informações necessárias para renderizar a visualização de destino.

O evento de navegação no histórico NÃO é disparado no carregamento inicial da página — apenas durante a navegação. Renderize a visualização inicial a partir de location na inicialização e, depois, deixe o evento cuidar das navegações seguintes. Sem isso, a página inicial fica em branco quando a primeira navegação para trás chega.

Para roteamento baseado exclusivamente em fragmentos (endereços como /#/about), o evento hashchange é disparado quando o fragmento muda. O evento de navegação no histórico também é disparado para alterações de caminho. As SPAs modernas usam a API de histórico e esse evento; o roteamento por fragmentos é legado.

Para fazer um clique comum em <a> disparar uma navegação no cliente, intercepte o clique, chame preventDefault e execute pushState + renderPage. Verifique as teclas modificadoras (clique com Cmd/Ctrl para abrir uma nova aba) e deixe esses cliques seguirem o comportamento padrão.

Os navegadores tentam restaurar automaticamente a posição de rolagem durante a navegação para trás, mas isso não é confiável em SPAs porque o conteúdo é renderizado de forma assíncrona. Salve a rolagem no estado de pushState e restaure-a durante a navegação no histórico: window.scrollTo(0, e.state?.scroll ?? 0).

Se renderPage buscar dados de forma assíncrona, o endereço será atualizado antes de o conteúdo chegar. Mostre um estado de carregamento e depois renderize. Evite condições de corrida nas quais o usuário clica em Voltar durante uma busca e o resultado da busca cancelada sobrescreve a nova visualização.

React Router, Vue Router e o roteador do SvelteKit envolvem a API de histórico e o evento de navegação no histórico. Mesmo sem uma estrutura, o mecanismo subjacente é o mesmo — escutar o evento, interceptar links e chamar pushState. Quando a sobrecarga for importante, crie seu próprio roteador em cerca de 50 linhas de JavaScript puro.

A configuração de cada visualização pode anexar ouvintes de eventos e temporizadores. Sem uma desmontagem explícita quando a visualização muda (durante a navegação no histórico ou no invólucro de pushState), os ouvintes se acumulam e degradam o desempenho ao longo do tempo. Acompanhe as inscrições de cada visualização com um AbortController e aborte-as quando a visualização mudar.

Por que o evento de navegação no histórico NÃO é disparado quando você chama history.pushState por conta própria?

O evento de navegação no histórico é disparado durante a navegação para trás ou para frente do navegador, dando acesso ao estado salvo e à nova localização. Ele não é disparado por pushState/replaceState (seu código já sabe o que fez) nem no carregamento inicial da página (renderize manualmente). Intercepte cliques em links para a navegação de SPA, salve a posição de rolagem no estado e desmonte os ouvintes quando a visualização mudar para evitar vazamentos.