UI Compartilhada com +layout.svelte

Em qualquer aplicação com múltiplas páginas, muitas rotas compartilham elementos estruturais: uma barra de navegação, uma barra lateral, um rodapé, um banner exibindo o usuário logado. A abordagem ingênua é importar e renderizar esses elementos em cada arquivo +page.svelte. Isso funciona até o momento em que você precisa alterar algo — então você acaba modificando dezenas de arquivos para o que deveria ser uma edição de uma linha.

O SvelteKit resolve isso com layouts — componentes que envolvem suas rotas descendentes com UI compartilhada. Um layout é executado uma vez quando o usuário entra em sua subárvore e permanece montado enquanto ele navega entre as rotas filhas. As páginas entram e saem dentro dele; o layout permanece.

Uma hierarquia de layouts bem projetada pode eliminar centenas de linhas de código duplicado e tornar triviais as mudanças globais de UI. Uma mal projetada força gambiarras incômodas. Dedique alguns minutos para mapear sua estrutura de layouts antes de construir — isso traz retornos significativos.

O Layout Raiz

O layout mais importante é o layout raiz. Ele fica no nível superior do seu diretório de rotas e envolve absolutamente todas as páginas da sua aplicação.

src/routes/
├── +layout.svelte         → Root layout (wraps everything)
├── +page.svelte           → Homepage
└── about/
    └── +page.svelte       → About page

Pense nele como a estrutura base do seu site — a estrutura que nunca muda enquanto o conteúdo da página é trocado dentro dela.

<!-- src/lib/components/Navigation.svelte -->
<nav>
	<a href="/">Home</a>
	<a href="/about">About</a>
	<a href="/blog">Blog</a>
	<a href="/contact">Contact</a>
</nav>

<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import Navigation from '$lib/components/Navigation.svelte'

	let { children } = $props()
</script>

<div class="app">
	<header>
		<Navigation />
	</header>

	<main>
		{@render children()}
	</main>

	<footer>
		<p>&copy; 2025 My Amazing Website</p>
	</footer>
</div>

<style>
	.app {
		display: flex;
		flex-direction: column;
		min-height: 100vh;
	}

	main {
		flex: 1;
		padding: 2rem;
	}
</style>

O Snippet `children`

Se você vem do Svelte 4, talvez esteja procurando por <slot />. No Svelte 5, os slots foram substituídos por snippets.

A prop children é um snippet especial que representa o conteúdo "dentro" do layout — o componente de página ou layout aninhado que ocupa essa rota. Você o renderiza com {@render children()}.

Esta é a regra mais crítica: você deve sempre renderizar children(). Se esquecer, nenhum conteúdo de página será exibido:

<!-- WRONG: Pages will never show -->
<script lang="ts">
  let { children } = $props()
</script>
<nav>Navigation</nav>
<footer>Footer</footer>

<!-- CORRECT: Always render children -->
<script lang="ts">
  let { children } = $props()
</script>
<nav>Navigation</nav>
<main>{@render children()}</main>
<footer>Footer</footer>

Layouts Aninhados

Layouts podem ser aninhados. Um layout dentro de um subdiretório envolve as páginas daquele diretório, mas ele próprio é envolvido pelo layout pai acima dele.

Exemplo: Layout da Seção Blog

Imagine uma seção de blog que precisa de uma barra lateral, mas a página inicial não. Crie um +layout.svelte dentro do diretório do blog:

src/routes/
├── +layout.svelte         → Root layout (wraps everything)
├── +page.svelte           → Homepage (no sidebar)
└── blog/
    ├── +layout.svelte     → Blog layout (adds sidebar)
    ├── +page.svelte       → Blog index
    └── [slug]/
        └── +page.svelte   → Individual blog post

<!-- src/routes/blog/+layout.svelte -->
<script lang="ts">
	let { children } = $props()
</script>

<div class="blog-layout">
	<aside>
		<h3>Categories</h3>
		<ul>
			<li><a href="/blog?category=tech">Tech</a></li>
			<li><a href="/blog?category=life">Life</a></li>
			<li><a href="/blog?category=tutorials">Tutorials</a></li>
		</ul>
	</aside>

	<div class="content">
		{@render children()}
	</div>
</div>

<style>
	.blog-layout {
		display: grid;
		grid-template-columns: 250px 1fr;
		gap: 2rem;
	}
</style>

Visualizando a Hierarquia

Quando um usuário visita /blog/my-first-post, o SvelteKit constrói a página como uma pilha de componentes aninhados, de fora para dentro:

Root Layout (+layout.svelte)
└── Blog Layout (blog/+layout.svelte)
    └── Blog Post Page (blog/[slug]/+page.svelte)

A estrutura HTML resultante reflete exatamente esse aninhamento:

<!-- From Root Layout -->
<div class="app">
	<header>...</header>
	<main>
		<!-- From Blog Layout -->
		<div class="blog-layout">
			<aside>...</aside>
			<div class="content">
				<!-- From Page -->
				<article>...</article>
			</div>
		</div>
	</main>
	<footer>...</footer>
</div>

Recebendo Dados em Layouts

Layouts podem receber dados de funções de carregamento, assim como as páginas. Os dados vêm de +layout.js ou +layout.server.js no mesmo diretório e estão disponíveis junto com children em $props():

<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import type { LayoutProps } from './$types'

	let { data, children }: LayoutProps = $props()
</script>

<header>
	{#if data.user}
		<span>Welcome, {data.user.name}</span>
		<a href="/logout">Logout</a>
	{:else}
		<a href="/login">Login</a>
	{/if}
</header>

<main>
	{@render children()}
</main>

Abordaremos o carregamento de dados em layouts nos próximos artigos: +layout.js e +layout.server.js.

Grupos de Layout

À medida que sua aplicação cresce, você se deparará com uma necessidade comum: seções diferentes requerem layouts completamente diferentes, mas você não quer que o nome da seção apareça na URL. Uma página inicial de marketing e um painel de usuário ficam ambos no nível superior — / e /dashboard — mas têm aparências completamente distintas. A página inicial tem uma imagem hero e um grande botão CTA; o painel tem uma barra de navegação lateral.

Um único layout raiz não consegue servir a ambos sem se tornar uma bagunça condicional. Mas sem alguma ferramenta organizacional, você teria que usar prefixos de URL como /marketing/ e /app/ apenas para ter hierarquias de layout separadas.

A solução do SvelteKit: grupos de layout. Envolva o nome de um diretório em parênteses e ele cria uma hierarquia de layout separada sem adicionar nada à URL. A pasta (marketing) existe apenas para a lógica de roteamento do SvelteKit — os usuários nunca a veem na barra de endereços.

src/routes/
├── (marketing)/
│   ├── +layout.svelte     → Marketing layout (big headers, CTAs)
│   ├── +page.svelte       → / (homepage)
│   ├── about/
│   │   └── +page.svelte   → /about
│   └── pricing/
│       └── +page.svelte   → /pricing
├── (app)/
│   ├── +layout.svelte     → App layout (sidebar, compact)
│   ├── dashboard/
│   │   └── +page.svelte   → /dashboard
│   └── settings/
│       └── +page.svelte   → /settings
└── +layout.svelte         → Root layout (wraps both groups)

Os parênteses dizem ao SvelteKit: use isso para organização, não para roteamento. Um visitante vê /about, não /(marketing)/about.

Os grupos de layout são perfeitos para manter designs radicalmente diferentes dentro da mesma aplicação — como um site público de marketing e um painel privado — sem poluir as URLs. Eles também permitem aplicar proteção de autenticação a uma seção inteira com um único +layout.server.js.

Isolamento de Erros: Um Superpoder Oculto

Um benefício frequentemente negligenciado dos layouts aninhados é o isolamento de erros. Quando algo dá errado em uma rota aninhada, o SvelteKit encontra o +error.svelte mais próximo e renderiza o erro ali — os layouts pai permanecem ativos.

<!-- src/routes/dashboard/widget/+error.svelte -->
<script lang="ts">
	import { page } from '$app/state'
</script>

<div class="error-container">
	<h2>Widget Error</h2>
	<p>Something went wrong loading this widget, but the rest of your dashboard still works!</p>
	<pre>{JSON.stringify(page.error, null, 2)}</pre>
</div>

Um widget do painel com falha não derruba a barra lateral nem a navegação. Os usuários podem continuar trabalhando enquanto você corrige o problema.

Saindo dos Layouts

Às vezes uma página precisa sair da sua hierarquia de layouts. O exemplo clássico: um relatório que precisa ser incorporado em um iframe deve renderizar sem nenhum elemento de navegação.

Use a sintaxe @ para redefinir para um ancestral de layout específico:

src/routes/
├── +layout.svelte              → Root layout
├── (app)/
│   ├── +layout.svelte          → App layout
│   └── dashboard/
│       └── reports/
│           ├── +page.svelte        → Uses full app layout
│           └── [id]/
│               └── embed/
│                   └── +page@.svelte → Resets to root layout only

+page@.svelte — Renderiza apenas dentro do layout raiz (ignora todos os layouts intermediários)
+page@(app).svelte — Renderiza dentro do layout do grupo (app) (ignora layouts mais profundos)

A página de incorporação exibe o conteúdo do relatório sem nenhum elemento visual do painel — perfeito para iframes. Os mesmos dados, um contexto de apresentação completamente diferente.

Persistência de Layout

Uma das coisas mais importantes a entender sobre layouts é que eles não remontam durante a navegação entre rotas irmãs. Quando um usuário clica de /blog/post-a para /blog/post-b, o layout do blog permanece ativo — o SvelteKit substitui apenas o conteúdo do +page.svelte dentro dele.

É por isso que o estado do layout sobrevive às transições de página dentro de uma seção. A posição de rolagem de uma barra lateral, um alternador aberto/fechado, uma animação em andamento — tudo isso persiste porque o componente de layout nunca é desmontado:

<!-- src/routes/blog/+layout.svelte -->
<script lang="ts">
	let { children } = $props()

	// Persists when navigating between blog posts.
	// Resets only when leaving /blog entirely.
	let sidebarOpen = $state(true)
</script>

<div class="blog-layout">
	<button onclick={() => (sidebarOpen = !sidebarOpen)}> Toggle Sidebar </button>

	{#if sidebarOpen}
		<aside>Sidebar content</aside>
	{/if}

	<main>
		{@render children()}
	</main>
</div>

O layout remonta apenas quando o usuário navega para uma rota fora de sua subárvore — por exemplo, saindo de /blog completamente e indo para /about. Isso significa que a inicialização custosa do layout (buscar categorias de navegação, inicializar bibliotecas, estabelecer conexões WebSocket) acontece uma vez por visita à seção, não uma vez por página.

Padrões Comuns

Conteúdo de Layout Condicional

Use o objeto page de $app/state para renderizar condicionalmente a UI com base na rota atual:

<script lang="ts">
	import { page } from '$app/state'
	let { children } = $props()
</script>

<header>
	<nav>
		<a href="/">Home</a>
		{#if page.url.pathname.startsWith('/admin')}
			<a href="/admin/users">Users</a>
			<a href="/admin/settings">Settings</a>
		{/if}
	</nav>
</header>

{@render children()}

Indicador de Carregamento de Navegação

Exiba uma barra de progresso durante a navegação. No Svelte 5, navigating vem de $app/state e é acessado diretamente — sem prefixo $, não é uma store:

<script lang="ts">
	import { navigating } from '$app/state'
	let { children } = $props()
</script>

{#if navigating}
	<div class="loading-bar"></div>
{/if}

{@render children()}

<style>
	.loading-bar {
		position: fixed;
		top: 0;
		left: 0;
		right: 0;
		height: 3px;
		background: var(--brand);
		animation: loading 1s ease-in-out infinite;
	}

	@keyframes loading {
		0% {
			transform: translateX(-100%);
		}
		100% {
			transform: translateX(100%);
		}
	}
</style>

Conclusão

O arquivo +layout.svelte representa a solução do SvelteKit para um dos desafios mais persistentes do desenvolvimento web: compartilhar estrutura de UI sem repetição ou complexidade. Ao definir layouts como componentes aninhados que envolvem seus descendentes, o SvelteKit cria uma hierarquia natural onde responsabilidades compartilhadas ficam nos níveis apropriados — navegação global no root, barras laterais específicas de seção em layouts aninhados, e conteúdo único de página nas próprias páginas.

A sintaxe {@render children()} é o mecanismo que compõe toda a sua aplicação — cada rota renderiza dentro da cadeia de wrappers de layout acima dela, e os layouts persistem durante a navegação dentro de sua subárvore para que configurações custosas aconteçam apenas uma vez.

Combinado com grupos de layout para diferentes seções do site, limites de erro que contêm falhas sem derrubar toda a UI, e a capacidade de resetar layouts quando uma página realmente precisa ficar sozinha, esse sistema fornece a flexibilidade para construir desde blogs simples até aplicações complexas, mantendo-se firmemente dentro das convenções do framework.

Principais Pontos

+layout.svelte envolve todas as rotas descendentes — UI compartilhada que persiste durante a navegação, com layouts aninhados formando uma hierarquia de componentes combináveis
{@render children()} é obrigatório — renderiza o componente de página ou layout aninhado que ocupa essa rota; omiti-lo torna todas as páginas invisíveis
O layout root envolve tudo — src/routes/+layout.svelte é o shell HTML de toda a aplicação; erros em sua função de load recorrem a src/error.html
Layouts recebem dados via $props() no Svelte 5, populados por +layout.js ou +layout.server.js — tanto data quanto children vêm de $props()
Layouts persistem dentro de sua subárvore — eles só remontam quando o usuário navega para fora do escopo de sua rota, preservando estado e evitando configurações redundantes
Grupos de layout organizam rotas sem poluir a URL — pastas (authenticated) e (marketing) criam hierarquias de layout separadas; os parênteses são invisíveis na URL final
navigating de $app/state é um valor reativo simples (não uma store) — use-o sem o prefixo $ para exibir indicadores de carregamento durante a navegação
Quebre a herança de layout com o reset @ — +page@.svelte renderiza apenas sob o layout root, ignorando todos os layouts intermediários quando uma página precisa ficar sozinha

Veja Também

Documentação Oficial do SvelteKit - Layouts - O guia oficial para componentes de layout
Grupos de Layout - Organizando hierarquias de rotas
page de $app/state — Estado de navegação e rota
Snippets no Svelte 5 - Entendendo a sintaxe {@render}
Quebrando Layouts - Sintaxe de reset @