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 autenticado. A abordagem ingênua é importar e renderizar esses elementos em cada arquivo +page.svelte. Isso funciona até o momento em que você precisa mudar algo — então você acaba alterando dezenas de arquivos para o que deveria ser uma edição de uma única 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 o usuário navega entre as rotas filhas. As páginas aparecem e desaparecem dentro dele; o layout permanece.

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

O Layout Raiz

O layout mais importante é o layout raiz. Ele fica no nível superior do seu diretório de rotas e envolve 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 o esqueleto do seu site — a estrutura que nunca muda enquanto o conteúdo da página é substituído 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, pode estar 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 de 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 distintos, mas você não quer que o nome da seção apareça na URL. Uma página inicial de marketing e um painel do usuário ficam ambos no nível superior — / e /dashboard — mas têm aparências totalmente diferentes. A página inicial tem uma imagem de destaque e um grande botão de CTA; o painel tem uma barra de navegação lateral.

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

A solução do SvelteKit: grupos de layout. Envolva o nome de um diretório entre 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.

Grupos de layout são perfeitos para manter designs radicalmente diferentes dentro do mesmo aplicativo — como um site público de marketing e um painel privado — sem poluir as URLs. Eles também permitem que você aplique 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 ignorado 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 lá — os layouts pai permanecem vivos.

<!-- 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 com falha no painel 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 ser renderizado 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 os layouts mais profundos)

A página de incorporação exibe o conteúdo do relatório sem nenhum elemento do painel — perfeita 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 são remontados 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 vivo — 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 é remontado apenas quando o usuário navega para uma rota fora de sua subárvore — por exemplo, saindo completamente de /blog e indo para /about. Isso significa que configurações custosas de layout (buscar categorias de navegação, inicializar bibliotecas, estabelecer conexões WebSocket) acontecem 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 as preocupações compartilhadas vivem nos níveis apropriados — navegação global no layout raiz, barras laterais específicas de seção em layouts aninhados e conteúdo exclusivo 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 entre navegações dentro de sua subárvore, de modo que configurações custosas acontecem 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 redefinir layouts quando uma página realmente precisa ficar isolada, esse sistema oferece a flexibilidade para construir desde blogs simples até aplicações complexas, mantendo-se firmemente dentro das convenções do framework.

Pontos-Chave

+layout.svelte envolve todas as rotas descendentes — UI compartilhada que persiste entre navegações, com layouts aninhados formando uma hierarquia de componentes combináveis
{@render children()} é obrigatório — renderiza o componente de página ou o layout aninhado que ocupa esta rota; omiti-lo torna todas as páginas invisíveis
O layout raiz envolve tudo — src/routes/+layout.svelte é o shell HTML de toda a aplicação; erros em sua função de carregamento recaem sobre 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ó são remontados quando o usuário navega para fora do escopo de sua rota, preservando o estado e evitando configurações redundantes
Grupos de layout organizam rotas sem poluir as URLs — 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 somente sob o layout raiz, ignorando todos os layouts intermediários quando uma página precisa ficar isolada

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 @