Navegação no SvelteKit

Em muitos frameworks SPA, a navegação é algo que você configura manualmente. Você importa um componente <Link>, registra rotas em um objeto de roteador e chama funções imperativas navigate() sempre que a URL precisa mudar programaticamente. Deixar qualquer uma dessas etapas de lado faz o navegador realizar um recarregamento completo ou simplesmente não acontece nada.

O SvelteKit adota uma posição fundamentalmente diferente: a plataforma já sabe como a navegação funciona. O navegador navega entre documentos há trinta anos. As tags <a> padrão, a API de histórico e os envios de formulário são primitivos web de primeira classe. O papel do SvelteKit é aprimorá-los, não substituí-los.

A filosofia de aprimoramento progressivo do SvelteKit significa que sua navegação funciona mesmo quando o JavaScript falha. Isso não é apenas sobre casos extremos — é sobre construir aplicações robustas. Sempre comece com HTML padrão e depois aprimore com JavaScript.

A Tag Âncora Padrão

Para criar um link para outra página no SvelteKit, basta usar HTML padrão:

<!-- Standard HTML works perfectly -->
<a href="/about">About Us</a>
<a href="/blog">Blog</a>
<a href="/contact">Contact</a>

Isso é melhor por diversas razões:

Acessibilidade: Leitores de tela e tecnologias assistivas entendem as tags <a> perfeitamente
Resiliência: Se o JavaScript falhar ao carregar, o link ainda funciona (apenas realiza um recarregamento completo da página)
Simplicidade: Você não precisa importar um componente especial só para criar um link
SEO: Os mecanismos de busca entendem e seguem links padrão

Navegação do Lado do Cliente

Mesmo que você escreva HTML padrão, o SvelteKit atualiza esses links automaticamente. Quando o JavaScript está carregado e o usuário clica em um link interno:

Interceptação: O roteador do lado do cliente do SvelteKit captura o evento de clique
Prevenção: Ele impede o recarregamento completo padrão do navegador
Busca: Ele busca apenas os dados e o código necessários para a próxima página
Troca: Ele substitui o componente da página atual pelo novo, mantendo os layouts intactos

Essa atualização é transparente e progressiva. Se o JavaScript ainda não foi carregado ou falhar completamente, o link ainda funciona — apenas realiza um recarregamento completo da página. Sua navegação degrada graciosamente em vez de quebrar. Isso faz uma diferença significativa: o modo de falha de um link padrão é um carregamento de página um pouco mais lento, não uma página quebrada.

Pré-carregamento

Você pode fazer sua aplicação parecer ainda mais rápida dizendo ao SvelteKit para começar a carregar a próxima página antes mesmo de o usuário clicar.

Pré-carregamento ao Passar o Mouse

Adicione o atributo data-sveltekit-preload-data à sua tag <body> (em src/app.html):

<!-- src/app.html -->
<body data-sveltekit-preload-data="hover">
	<div style="display: contents">%sveltekit.body%</div>
</body>

Agora, quando um usuário passa o mouse sobre um link, o SvelteKit começa a buscar os dados daquela página imediatamente. Quando o usuário clica (geralmente 100-200ms depois), os dados frequentemente já estão disponíveis, fazendo a transição parecer instantânea.

Opções de Pré-carregamento

Valor	Comportamento
`hover`	Pré-carrega quando o mouse passa sobre o link
`tap`	Pré-carrega quando o usuário começa a pressionar (toque ou mouse)
`off`	Desativa o pré-carregamento

Pré-carregamento por Link

Você também pode controlar o pré-carregamento em links individuais:

<!-- Always preload this important link on hover -->
<a href="/pricing" data-sveltekit-preload-data="hover">Pricing</a>

<!-- Don't preload this link (maybe it's expensive) -->
<a href="/reports" data-sveltekit-preload-data="off">Reports</a>

<!-- Only preload the code, not the data -->
<a href="/dashboard" data-sveltekit-preload-code>Dashboard</a>

Use data-sveltekit-preload-code para rotas com bundles de JavaScript pesados. Isso baixa o código ao passar o mouse, mas aguarda para buscar os dados até o clique, equilibrando desempenho com custo de dados.

Construindo um Componente de Navegação

Vamos construir um componente de navegação reutilizável que destaca a página atual:

<!-- src/lib/components/Navigation.svelte -->
<script lang="ts">
	import { page } from '$app/state'
</script>

<nav>
	<a href="/" aria-current={page.url.pathname === '/' ? 'page' : undefined}> Home </a>
	<a href="/about" aria-current={page.url.pathname === '/about' ? 'page' : undefined}> About </a>
	<a href="/blog" aria-current={page.url.pathname.startsWith('/blog') ? 'page' : undefined}>
		Blog
	</a>
	<a href="/contact" aria-current={page.url.pathname === '/contact' ? 'page' : undefined}>
		Contact
	</a>
</nav>

<style>
	nav {
		display: flex;
		gap: 1rem;
		padding: 1rem;
		background: var(--surface-2);
	}

	a {
		text-decoration: none;
		color: var(--text);
		padding: 0.5rem 1rem;
		border-radius: 4px;
		transition: background-color 0.2s;
	}

	a:hover {
		background: var(--surface-3);
	}

	/* aria-current is the accessible way to style active links */
	a[aria-current='page'] {
		background: var(--brand);
		color: white;
	}
</style>

O objeto page do $app/state (novo no Svelte 5) fornece informações sobre a página atual, incluindo a URL. Usamos isso para destacar o item de navegação ativo.

Navegação Programática com `goto()`

Às vezes você precisa navegar em resposta a uma ação — após o envio de um formulário, quando um temporizador expira ou quando alguma condição é satisfeita. Use a função goto:

<script lang="ts">
	import { goto } from '$app/navigation'

	async function handleLogin() {
		const success = await login()

		if (success) {
			// Navigate to dashboard
			goto('/dashboard')
		}
	}
</script>

<button onclick={handleLogin}>Log In</button>

Opções do `goto()`

import { goto } from '$app/navigation'

// Basic navigation
goto('/about')

// Replace history entry (back button won't return here)
goto('/wizard/step-2', { replaceState: true })

// Prevent scroll reset
goto('/blog/page/2', { noScroll: true })

// Invalidate all load functions and refetch
goto('/dashboard', { invalidateAll: true })

Redirecionamentos em Funções de Carregamento

Para redirecionamentos do lado do servidor, use o helper redirect em suas funções de carregamento:

// src/routes/admin/+page.server.ts
import { redirect } from '@sveltejs/kit'
import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ locals }) => {
	if (!locals.user) {
		// 303 = redirect after form submission
		// 307 = temporary redirect
		// 308 = permanent redirect
		redirect(303, '/login')
	}

	return {
		user: locals.user
	}
}

Links Externos

Links para sites externos funcionam normalmente e não serão interceptados:

<!-- External links open normally -->
<a href="https://svelte.dev">Svelte Docs</a>

<!-- Force a full page reload for internal link -->
<a href="/legacy-page" data-sveltekit-reload>Legacy Page</a>

<!-- Open in new tab -->
<a href="https://github.com" target="_blank" rel="noopener">GitHub</a>

Eventos de Navegação

Você pode escutar eventos de navegação para analytics, indicadores de carregamento ou outros efeitos colaterais:

<script lang="ts">
	import { beforeNavigate, afterNavigate } from '$app/navigation'

	beforeNavigate(({ from, to, cancel }) => {
		// Runs before leaving current page
		if (hasUnsavedChanges && !confirm('Discard changes?')) {
			cancel()
		}
	})

	afterNavigate(({ from, to, type }) => {
		// Runs after arriving at new page
		// type can be 'link', 'popstate', 'goto', etc.
		analytics.track('page_view', { path: to?.url.pathname })
	})
</script>

Use beforeNavigate para avisar usuários sobre alterações não salvas, e afterNavigate para rastreamento de analytics ou lógica de restauração de rolagem.

O Objeto de Estado `page`

O objeto page do $app/state contém informações úteis:

<script lang="ts">
	import { page } from '$app/state'
</script>

<p>Current path: {page.url.pathname}</p>
<p>Search params: {page.url.searchParams.toString()}</p>
<p>Route ID: {page.route.id}</p>
<p>Route params: {JSON.stringify(page.params)}</p>

{#if page.error}
	<p>Error: {page.error.message}</p>
{/if}

{#if page.data.user}
	<p>Logged in as: {page.data.user.name}</p>
{/if}

Preservação de Estado (Snapshots)

Quando um usuário navega para fora de uma página e clica em "voltar", ele espera que a página esteja exatamente como deixou — posição de rolagem restaurada, entradas de formulário intactas. O SvelteKit lida com a restauração de rolagem automaticamente, mas o estado reativo de componente (como texto digitado em uma caixa de pesquisa) não sobrevive a um desmonte e remonte completo do componente por padrão. Os Snapshots resolvem isso.

Um snapshot é um par de funções: capture é executada quando o componente é desmontado (preservando o estado no histórico de sessão), e restore é executada quando o componente é remontado a partir do histórico (reinstalando esse estado).

No Svelte 5, snapshot é exportado do <script> de instância regular usando export const. Este é um dos exports não-prop que o Svelte 5 preserva — export let para declarar props foi substituído por $props(), mas export const para expor valores na instância do componente ainda funciona. As funções capture e restore fecham sobre o estado reativo search no mesmo bloco de script:

<script lang="ts">
	import type { Snapshot } from './$types'

	let search = $state('')

	export const snapshot: Snapshot<string> = {
		capture: () => search,
		restore: (value) => {
			search = value
		}
	}
</script>

<input bind:value={search} placeholder="Search..." />

Quando capture() é chamado antes de navegar para outra página, ele lê o valor atual de search. Quando restore(value) é chamado ao navegar de volta, ele escreve novamente em search e a reatividade do Svelte atualiza o input automaticamente. O estado é armazenado na entrada do histórico de sessão do navegador, portanto sobrevive à navegação de volta, mas é descartado quando a aba é fechada.

Snapshots são particularmente úteis para interfaces de busca, filtros, estado de paginação e qualquer estado de UI efêmero que melhore a experiência do usuário ao navegar de volta.

Padrões Comuns

Helper de Link Ativo

Crie uma função reutilizável para determinar se um link está ativo:

// src/lib/utils/navigation.ts
export function isActive(pathname: string, href: string, exact = false): boolean {
	if (exact) {
		return pathname === href
	}
	return pathname === href || pathname.startsWith(href + '/')
}

<script lang="ts">
	import { page } from '$app/state'
	import { isActive } from '$lib/utils/navigation'
</script>

<a href="/blog" aria-current={isActive(page.url.pathname, '/blog') ? 'page' : undefined}> Blog </a>

Breadcrumbs

<script lang="ts">
	import { page } from '$app/state'

	// Convert /blog/posts/my-article to breadcrumb segments
	let segments = $derived(
		page.url.pathname
			.split('/')
			.filter(Boolean)
			.map((segment, index, arr) => ({
				name: segment.replace(/-/g, ' '),
				href: '/' + arr.slice(0, index + 1).join('/')
			}))
	)
</script>

<nav aria-label="Breadcrumb">
	<ol>
		<li><a href="/">Home</a></li>
		{#each segments as segment, i}
			<li>
				{#if i === segments.length - 1}
					<span aria-current="page">{segment.name}</span>
				{:else}
					<a href={segment.href}>{segment.name}</a>
				{/if}
			</li>
		{/each}
	</ol>
</nav>

Conclusão

O sistema de navegação do SvelteKit transforma a experiência tradicional de aplicações multi-página em algo que parece um aplicativo de página única, preservando os benefícios fundamentais da web. Ao fazer upgrade automaticamente das tags <a> padrão para navegação do lado do cliente, ele proporciona transições instantâneas sem exigir que os desenvolvedores aprendam novos componentes de link ou APIs de roteamento. O sistema inteligente de pré-carregamento torna a navegação praticamente instantânea, enquanto a função goto() e os hooks de navegação oferecem controle programático quando necessário.

Dominar a navegação no SvelteKit significa entender o equilíbrio entre o aprimoramento automático e o controle manual. Links padrão proporcionam a melhor experiência para a maioria dos casos, o pré-carregamento elimina a latência percebida, e os eventos de navegação habilitam analytics e guardas sem comprometer o fluxo principal de navegação. Combinados com a preservação de snapshots para o estado dos componentes e a store reativa page para estado derivado da URL, o SvelteKit oferece tudo o que é necessário para construir aplicações que pareçam rápidas, responsivas e nativas, mantendo-se fundamentalmente baseadas na web.

Pontos Principais

A navegação do lado do cliente é automática - tags <a href="/path"> padrão são interceptadas e convertidas em navegação no estilo SPA sem recarregamentos completos de página
O pré-carregamento elimina a latência percebida usando data-sveltekit-preload-data em links para buscar dados da rota ao passar o mouse, tornando a navegação praticamente instantânea
goto() habilita a navegação programática para envios de formulários, redirecionamentos após ações ou roteamento condicional baseado no estado da aplicação
redirect() em funções load lida com redirecionamentos do lado do servidor durante SSR ou carregamento de dados, lançando uma resposta de redirecionamento que o SvelteKit processa automaticamente
page de $app/state fornece estado reativo da URL com as propriedades url, params, route, status e data acessíveis de qualquer componente sem prop drilling
Hooks de navegação habilitam o controle do ciclo de vida - beforeNavigate para guardas/confirmações, onNavigate para View Transitions, afterNavigate para analytics/rastreamento
Snapshots preservam o estado transitório entre navegações usando a exportação snapshot, capturando inputs de formulários, posições de scroll ou estado de componentes que não devem ser perdidos
Estratégias de pré-carregamento oferecem controle granular - hover, tap, viewport ou off em links individuais, com padrões globais no app.html via atributos de dados

Veja Também

Documentação Oficial do SvelteKit - Navegação
goto() - API de navegação programática
page de $app/state — Estado reativo da página, URL e informações de rota
Ciclo de Vida de Navegação - hooks beforeNavigate, afterNavigate
Pré-carregamento - Estratégias e configuração de pré-carregamento
API de View Transitions - Animações nativas de transição de página
redirect() - Helper de redirecionamento do lado do servidor