Invocando Snippets com Precisão

Onde #snippet define blocos de marcação reutilizáveis, a tag @render dá vida a essas definições. Essa divisão de responsabilidades cria uma poderosa separação entre como o conteúdo é exibido e onde ele aparece.

Este tutorial pressupõe que você esteja familiarizado com os conceitos básicos de snippets do artigo #snippet. Aqui nos concentramos nos padrões de invocação: renderização opcional, seleção dinâmica, o padrão children e a construção de APIs de componentes sofisticadas.

Invocação Básica

O uso mais simples de @render chama um snippet sem argumentos:

{#snippet logo()}
	<svg viewBox="0 0 100 100" class="logo">
		<circle cx="50" cy="50" r="40" fill="currentColor" />
	</svg>
{/snippet}

<header>
	{@render logo()}
	<h1>My Application</h1>
</header>

<footer>
	{@render logo()}
</footer>

O snippet logo é definido uma vez, mas renderizado duas vezes. Qualquer alteração na definição é propagada automaticamente para ambos os locais.

Renderizando com Argumentos

Passe dados para snippets parametrizados:

{#snippet userCard(name, role)}
	<div class="user-card">
		<h3>{name}</h3>
		<span class="role">{role}</span>
	</div>
{/snippet}

{@render userCard('Alice Chen', 'Lead Developer')}
{@render userCard('Bob Smith', 'UI Designer')}

Os argumentos fluem para o snippet assim como argumentos de função. Para dados complexos, passe objetos:

{#snippet productCard(product)}
	<article class="product">
		<h3>{product.name}</h3>
		<p class="price">${product.price.toFixed(2)}</p>
	</article>
{/snippet}

{#each products as product (product.id)}
	{@render productCard(product)}
{/each}

Snippets Opcionais: Padrões de Renderização Segura

Um cenário comum: uma prop de snippet pode ou não ser fornecida. Tentar renderizar um snippet indefinido gera um erro. O Svelte oferece dois padrões para lidar com isso de forma elegante.

1. Encadeamento Opcional

A abordagem mais simples utiliza o operador de encadeamento opcional do JavaScript:

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

<button class="btn">
	{@render icon?.()}
	{@render children?.()}
</button>

Se icon for undefined, icon?.() é avaliado como undefined e nada é renderizado — sem erros, sem elemento vazio. Isso é ideal quando a ausência de conteúdo simplesmente significa "não exibir nada".

2. Renderização Condicional com Fallback

Quando você precisa de conteúdo de fallback para snippets ausentes, use um bloco {#if}:

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

<article class="card">
	{#if header}
		<header class="card-header">
			{@render header()}
		</header>
	{:else}
		<header class="card-header">
			<span class="default-header">Untitled</span>
		</header>
	{/if}

	<div class="card-body">
		{#if children}
			{@render children()}
		{:else}
			<p class="empty-state">No content provided</p>
		{/if}
	</div>

	{@render footer?.()}
</article>

Isso demonstra ambos os padrões:

header possui um fallback quando ausente
children possui um fallback diferente (mensagem de estado vazio)
footer simplesmente não é renderizado se estiver ausente

Cadeias de Fallback em Cascata

Combine condicionais com encadeamento opcional para uma lógica de fallback sofisticada:

<script>
	let { primaryAction, secondaryAction, tertiaryAction } = $props()
</script>

<div class="action-bar">
	{#if primaryAction}
		{@render primaryAction()}
	{:else if secondaryAction}
		{@render secondaryAction()}
	{:else}
		{@render tertiaryAction?.()}
		{#if !tertiaryAction}
			<button class="default-action">Continue</button>
		{/if}
	{/if}
</div>

Isso cria um fallback em cascata: tenta primaryAction, depois secondaryAction, depois tertiaryAction e, por fim, um padrão fixo no código.

Seleção Dinâmica de Snippets

A tag render aceita qualquer expressão que seja avaliada como um snippet — não apenas identificadores. Isso habilita poderosos padrões dinâmicos.

Seleção com Ternário

Escolha entre snippets com base em uma condição:

<script>
	let isExpanded = $state(false)
</script>

{#snippet compactView(item)}
	<div class="compact">{item.title}</div>
{/snippet}

{#snippet expandedView(item)}
	<div class="expanded">
		<h3>{item.title}</h3>
		<p>{item.description}</p>
	</div>
{/snippet}

{#each items as item}
	{@render (isExpanded ? expandedView : compactView)(item)}
{/each}

<button onclick={() => (isExpanded = !isExpanded)}>
	{isExpanded ? 'Collapse' : 'Expand'} All
</button>

Os parênteses ao redor da expressão ternária são necessários — eles agrupam a expressão antes da invocação ().

Lógica Condicional para Múltiplas Opções

Para mais de duas opções, use blocos condicionais:

<script>
	let viewMode = $state('grid') // 'grid' | 'list' | 'table'
</script>

{#snippet gridView(items)}
	<div class="grid">
		{#each items as item}
			<div class="grid-card">{item.name}</div>
		{/each}
	</div>
{/snippet}

{#snippet listView(items)}
	<ul class="list">
		{#each items as item}
			<li class="list-item">{item.name}</li>
		{/each}
	</ul>
{/snippet}

{#snippet tableView(items)}
	<table>
		<tbody>
			{#each items as item}
				<tr><td>{item.name}</td><td>{item.status}</td></tr>
			{/each}
		</tbody>
	</table>
{/snippet}

{#if viewMode === 'grid'}
	{@render gridView(items)}
{:else if viewMode === 'list'}
	{@render listView(items)}
{:else}
	{@render tableView(items)}
{/if}

Seleção Baseada em Função

Para seleções com lógica complexa, encapsule a decisão em uma função:

<script>
	function getRenderer(item) {
		if (item.type === 'image') return imageRenderer
		if (item.type === 'video') return videoRenderer
		return fallbackRenderer
	}
</script>

{#snippet imageRenderer(item)}
	<img src={item.src} alt={item.alt} />
{/snippet}

{#snippet videoRenderer(item)}
	<video src={item.src} controls></video>
{/snippet}

{#snippet fallbackRenderer(item)}
	<div class="unknown-type">Unsupported: {item.type}</div>
{/snippet}

{#each mediaItems as item}
	{@render getRenderer(item)(item)}
{/each}

Os parênteses duplos — getRenderer(item)(item) — primeiro chamam a função para obter um snippet e, em seguida, invocam esse snippet.

Usando $derived para Seleção Dinâmica

Combine $derived com a seleção de snippets para uma renderização reativa e computada:

<script>
	let { items, filter = '' } = $props()

	let filteredItems = $derived(
		items.filter((item) => item.name.toLowerCase().includes(filter.toLowerCase()))
	)

	let hasResults = $derived(filteredItems.length > 0)
</script>

{#snippet itemList(items)}
	<ul>
		{#each items as item (item.id)}
			<li>{item.name}</li>
		{/each}
	</ul>
{/snippet}

{#snippet emptyState()}
	<div class="empty">
		<p>No items found matching "{filter}"</p>
	</div>
{/snippet}

{@render (hasResults ? itemList : emptyState)(filteredItems)}

O Padrão de Snippet `children`

Quando conteúdo é colocado dentro das tags de um componente sem um wrapper #snippet, o Svelte cria automaticamente um snippet chamado children:

<!-- Parent component usage -->
<Card>
	<h2>Welcome Back</h2>
	<p>You have 3 new notifications.</p>
</Card>

<!-- Card.svelte -->
<script>
	let { children } = $props()
</script>

<article class="card">
	{@render children?.()}
</article>

Passando Dados de Volta Através de children

Os componentes podem passar dados de volta para o snippet children, habilitando padrões de componentes "renderless" ou "headless":

<!-- DataProvider.svelte -->
<script>
	let { url, children } = $props()

	let data = $state(null)
	let loading = $state(true)
	let error = $state(null)

	$effect(() => {
		loading = true
		fetch(url)
			.then((r) => r.json())
			.then((d) => {
				data = d
				loading = false
			})
			.catch((e) => {
				error = e
				loading = false
			})
	})
</script>

{@render children?.({ data, loading, error })}

<!-- Usage -->
<DataProvider url="/api/users">
	{#snippet children({ data, loading, error })}
		{#if loading}
			<p>Loading...</p>
		{:else if error}
			<p>Error: {error.message}</p>
		{:else}
			<ul>
				{#each data as user}
					<li>{user.name}</li>
				{/each}
			</ul>
		{/if}
	{/snippet}
</DataProvider>

O DataProvider gerencia a lógica enquanto delega a renderização inteiramente aos consumidores.

Padrões de Design de API de Componentes

Ao construir componentes reutilizáveis, snippets e a tag render permitem projeção e personalização flexíveis de conteúdo. Existem dois padrões principais para passar snippets como props.

Props de Snippet Explícitos vs Implícitos

Snippets podem ser passados tanto explicitamente (como props nomeadas) quanto implicitamente (definidos dentro de tags de componente):

Explícito:

{#snippet header()}
	<th>Name</th><th>Email</th>
{/snippet}

<Table data={users} {header} />

Implícito:

<Table data={users}>
	{#snippet header()}
		<th>Name</th><th>Email</th>
	{/snippet}
</Table>

Ambas as abordagens resultam em comportamento idêntico — a escolha é estilística. Props implícitas agrupam visualmente snippets relacionados com o componente de destino.

Componente Flexível com Múltiplos Pontos de Renderização

<!-- DataTable.svelte -->
<script>
	let { data, header, row, emptyState } = $props()
</script>

<table class="data-table">
	{#if header}
		<thead>{@render header()}</thead>
	{/if}
	<tbody>
		{#if data.length > 0}
			{#each data as item (item.id)}
				{@render row(item)}
			{/each}
		{:else if emptyState}
			<tr><td colspan="100%">{@render emptyState()}</td></tr>
		{:else}
			<tr><td colspan="100%">No data available</td></tr>
		{/if}
	</tbody>
</table>

Uso:

<DataTable data={users}>
	{#snippet header()}
		<tr><th>Name</th><th>Email</th><th>Actions</th></tr>
	{/snippet}

	{#snippet row(user)}
		<tr>
			<td>{user.name}</td>
			<td>{user.email}</td>
			<td><button onclick={() => edit(user)}>Edit</button></td>
		</tr>
	{/snippet}

	{#snippet emptyState()}
		<div class="empty">
			<img src="/empty-table.svg" alt="" />
			<p>No users found</p>
		</div>
	{/snippet}
</DataTable>

Padrões do Mundo Real

Em aplicações reais, a tag render e os snippets habilitam padrões avançados para composição de componentes, contêineres de estado e estruturas recursivas. Vamos explorar exemplos práticos que você encontrará em aplicações em produção.

1. Composição de Layout

Componentes de layout frequentemente aceitam múltiplas props de snippet para diferentes regiões:

<!-- Layout.svelte -->
<script>
	let { header, sidebar, children, footer } = $props()
</script>

<div class="layout">
	<header class="layout-header">
		{#if header}
			{@render header()}
		{:else}
			<nav class="default-nav"><a href="/">Home</a></nav>
		{/if}
	</header>

	<div class="layout-body">
		{#if sidebar}
			<aside class="layout-sidebar">{@render sidebar()}</aside>
		{/if}
		<main class="layout-main">{@render children?.()}</main>
	</div>

	{@render footer?.()}
</div>

2. Padrão Modal/Dialog

Modais se beneficiam de projeção de conteúdo baseada em snippets e $bindable para gerenciamento de estado:

<!-- Modal.svelte -->
<script>
	let { isOpen = $bindable(false), title, children, footer } = $props()

	let dialogEl = $state(null)

	$effect(() => {
		if (isOpen && dialogEl) {
			dialogEl.showModal()
		} else if (!isOpen && dialogEl) {
			dialogEl.close()
		}
	})

	function handleClose() {
		isOpen = false
	}
</script>

<dialog bind:this={dialogEl} onclose={handleClose}>
	<header>
		{#if title}
			<h2>{title}</h2>
		{/if}
		<button onclick={handleClose} aria-label="Close">×</button>
	</header>

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

	{#if footer}
		<footer>{@render footer()}</footer>
	{/if}
</dialog>

<style>
	dialog {
		max-width: 500px;
		border-radius: 8px;
		border: 1px solid #ccc;
	}

	dialog::backdrop {
		background: rgba(0, 0, 0, 0.5);
	}
</style>

Uso:

<script>
	let showModal = $state(false)

	function handleDelete() {
		// Delete logic
		showModal = false
	}
</script>

<button onclick={() => (showModal = true)}>Delete Item</button>

<Modal bind:isOpen={showModal} title="Confirm Action">
	<p>Are you sure you want to delete this item? This action cannot be undone.</p>

	{#snippet footer()}
		<button onclick={() => (showModal = false)}>Cancel</button>
		<button onclick={handleDelete} class="danger">Delete</button>
	{/snippet}
</Modal>

3. Padrão de Componente de Abas

Abas demonstram seleção dinâmica de snippet com gerenciamento de estado:

<!-- Tabs.svelte -->
<script>
	let { tabs = [], activeTab = $bindable(0), children } = $props()
</script>

<div class="tabs">
	<div role="tablist">
		{#each tabs as tab, index}
			<button
				role="tab"
				aria-selected={activeTab === index}
				tabindex={activeTab === index ? 0 : -1}
				onclick={() => (activeTab = index)}
			>
				{tab}
			</button>
		{/each}
	</div>

	<div role="tabpanel">
		{@render children?.(activeTab)}
	</div>
</div>

<style>
	.tabs {
		border: 1px solid #ddd;
		border-radius: 4px;
	}

	[role='tablist'] {
		display: flex;
		gap: 4px;
		border-bottom: 1px solid #ddd;
		padding: 8px;
	}

	[role='tab'] {
		padding: 8px 16px;
		border: none;
		background: transparent;
		cursor: pointer;
	}

	[role='tab'][aria-selected='true'] {
		border-bottom: 2px solid blue;
	}

	[role='tabpanel'] {
		padding: 16px;
	}
</style>

Uso:

<script>
	let activeTab = $state(0)
</script>

<Tabs tabs={['Profile', 'Settings', 'Notifications']} bind:activeTab>
	{#snippet children(index)}
		{#if index === 0}
			<h3>Profile</h3>
			<p>Manage your profile information</p>
		{:else if index === 1}
			<h3>Settings</h3>
			<p>Configure your preferences</p>
		{:else}
			<h3>Notifications</h3>
			<p>Manage notification settings</p>
		{/if}
	{/snippet}
</Tabs>

4. Padrão de Estado de Carregamento

Trate estados de carregamento, erro e sucesso de forma elegante:

<!-- LoadingState.svelte -->
<script>
	let { loading, error, data, skeleton, errorFallback, children } = $props()
</script>

{#if loading}
	{#if skeleton}
		{@render skeleton()}
	{:else}
		<div class="skeleton-loader" aria-busy="true" aria-live="polite">
			<div class="skeleton-line"></div>
			<div class="skeleton-line"></div>
			<div class="skeleton-line short"></div>
		</div>
	{/if}
{:else if error}
	{#if errorFallback}
		{@render errorFallback(error)}
	{:else}
		<div class="error-state" role="alert">
			<p>Something went wrong: {error.message}</p>
		</div>
	{/if}
{:else}
	{@render children?.(data)}
{/if}

<style>
	.skeleton-loader {
		padding: 16px;
	}

	.skeleton-line {
		height: 16px;
		background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
		background-size: 200% 100%;
		animation: loading 1.5s infinite;
		margin-bottom: 8px;
		border-radius: 4px;
	}

	.skeleton-line.short {
		width: 60%;
	}

	@keyframes loading {
		0% {
			background-position: 200% 0;
		}
		100% {
			background-position: -200% 0;
		}
	}
</style>

Uso:

<script>
	let users = $state(null)
	let loading = $state(true)
	let error = $state(null)

	$effect(() => {
		fetch('/api/users')
			.then((r) => r.json())
			.then((data) => {
				users = data
				loading = false
			})
			.catch((err) => {
				error = err
				loading = false
			})
	})
</script>

<LoadingState {loading} {error} data={users}>
	{#snippet skeleton()}
		<div class="user-skeleton">
			<div class="skeleton-avatar"></div>
			<div class="skeleton-text"></div>
			<div class="skeleton-text short"></div>
		</div>
	{/snippet}

	{#snippet errorFallback(err)}
		<div class="custom-error">
			<h3>Failed to load users</h3>
			<p>{err.message}</p>
			<button onclick={() => window.location.reload()}>Retry</button>
		</div>
	{/snippet}

	{#snippet children(userData)}
		<ul class="user-list">
			{#each userData as user (user.id)}
				<li>{user.name}</li>
			{/each}
		</ul>
	{/snippet}
</LoadingState>

5. Sistema de Notificações Toast

Construa um sistema de notificações flexível com renderização personalizável:

<!-- ToastContainer.svelte -->
<script>
	let { toasts = [], toast, position = 'top-right' } = $props()

	function removeToast(id) {
		toasts = toasts.filter((t) => t.id !== id)
	}
</script>

<div class="toast-container toast-{position}">
	{#each toasts as item (item.id)}
		{#if toast}
			{@render toast(item, removeToast)}
		{:else}
			<div class="toast toast-{item.type}">
				{item.message}
				<button onclick={() => removeToast(item.id)} aria-label="Close notification"> × </button>
			</div>
		{/if}
	{/each}
</div>

<style>
	.toast-container {
		position: fixed;
		z-index: 9999;
		display: flex;
		flex-direction: column;
		gap: 8px;
		padding: 16px;
	}

	.toast-top-right {
		top: 0;
		right: 0;
	}

	.toast {
		background: white;
		padding: 12px 16px;
		border-radius: 4px;
		box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
		display: flex;
		align-items: center;
		gap: 8px;
		min-width: 300px;
	}

	.toast-success {
		border-left: 4px solid green;
	}

	.toast-error {
		border-left: 4px solid red;
	}
</style>

Uso com renderização personalizada:

<script>
	let toasts = $state([])
	let nextId = $state(1)

	function addToast(type, title, message) {
		toasts = [...toasts, { id: nextId++, type, title, message }]
	}
</script>

<ToastContainer {toasts}>
	{#snippet toast(item, onClose)}
		<article class="custom-toast" class:success={item.type === 'success'}>
			<header>
				<strong>{item.title}</strong>
				<button onclick={() => onClose(item.id)} aria-label="Close">×</button>
			</header>
			<p>{item.message}</p>
		</article>
	{/snippet}
</ToastContainer>

<button onclick={() => addToast('success', 'Success!', 'Your changes have been saved.')}>
	Show Toast
</button>

6. Contêiner de Estado Sem Renderização

Um componente "sem renderização" gerencia o estado e o repassa para os filhos para renderização:

<!-- Toggleable.svelte -->
<script>
	let { children, initialOpen = false } = $props()

	let isOpen = $state(initialOpen)

	function toggle() {
		isOpen = !isOpen
	}

	function open() {
		isOpen = true
	}

	function close() {
		isOpen = false
	}
</script>

{@render children({ isOpen, toggle, open, close })}

Uso:

<Toggleable>
	{#snippet children({ isOpen, toggle })}
		<div class="accordion">
			<button onclick={toggle} aria-expanded={isOpen}>
				FAQ: How do I reset my password?
				<span>{isOpen ? '−' : '+'}</span>
			</button>
			{#if isOpen}
				<div class="accordion-body">
					<p>Click on "Forgot Password" on the login page...</p>
				</div>
			{/if}
		</div>
	{/snippet}
</Toggleable>

7. Renderização Recursiva (Estruturas em Árvore)

Snippets podem chamar a si mesmos para renderizar estruturas de dados recursivas:

<script>
	let tree = $state({
		name: 'Root',
		children: [
			{
				name: 'Documents',
				children: [{ name: 'Resume.pdf' }, { name: 'Cover-Letter.docx' }]
			},
			{
				name: 'Pictures',
				children: [{ name: 'beach.jpg' }, { name: 'sunset.png' }]
			}
		]
	})
</script>

{#snippet treeNode(node, depth = 0)}
	<div class="tree-node" style="--depth: {depth}">
		<button
			onclick={() => {
				if (node.children) {
					node.expanded = !node.expanded
				}
			}}
		>
			<span>{node.children ? (node.expanded ? '📂' : '📁') : '📄'}</span>
			<span>{node.name}</span>
		</button>

		{#if node.children && node.expanded}
			{#each node.children as child}
				{@render treeNode(child, depth + 1)}
			{/each}
		{/if}
	</div>
{/snippet}

{@render treeNode(tree)}

<style>
	.tree-node {
		padding-left: calc(var(--depth) * 1.5rem);
	}

	.tree-node button {
		display: flex;
		align-items: center;
		gap: 8px;
		background: none;
		border: none;
		padding: 4px 8px;
		cursor: pointer;
	}

	.tree-node button:hover {
		background: #f0f0f0;
	}
</style>

Integração com TypeScript

Tipar props de snippet melhora a experiência do desenvolvedor e a segurança de tipos. O Svelte fornece um tipo Snippet para esse fim:

<script lang="ts">
	import type { Snippet } from 'svelte'

	interface Props {
		data: User[]
		children: Snippet // No parameters
		row: Snippet<[User]> // One parameter
		cell?: Snippet<[User, keyof User]> // Optional, two parameters
	}

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

Para segurança de tipos genérica:

<script lang="ts" generics="T extends { id: string | number }">
	import type { Snippet } from 'svelte'

	interface Props {
		items: T[]
		renderItem: Snippet<[T, number]>
	}

	let { items, renderItem }: Props = $props()
</script>

<ul>
	{#each items as item, index (item.id)}
		<li>{@render renderItem(item, index)}</li>
	{/each}
</ul>

Armadilhas Comuns

Dominar a tag @render do Svelte desbloqueia padrões poderosos de composição, mas é fácil cometer erros sutis — especialmente ao trabalhar com snippets, seleção dinâmica ou conteúdo opcional. Compreender essas armadilhas vai ajudá-lo a evitar bugs e escrever código mais fácil de manter.

1. Esquecer de Invocar o Snippet

Um snippet sempre deve ser invocado com parênteses — mesmo que não receba argumentos. Omitir os parênteses não renderizará o snippet; em vez disso, apenas referencia a função do snippet sem chamá-la.

Dica: Sempre verifique se há parênteses () após o nome do seu snippet:

<!-- AVOID: Wrong: Just references the snippet -->
{@render mySnippet}

<!-- PREFERRED: Invokes the snippet -->
{@render mySnippet()}

2. Renderizando Snippets Indefinidos

Tentar renderizar um snippet que é undefined lançará um erro. Isso acontece frequentemente quando você espera que uma prop ou slot seja opcional, mas esquece de verificar se está ausente.

Solução: Use encadeamento opcional (?.()) ou verificações condicionais:

<!-- AVOID: Throws error if maybeSnippet is undefined -->
{@render maybeSnippet()}

<!-- PREFERRED: Safe with optional chaining -->
{@render maybeSnippet?.()}

<!-- PREFERRED: Safe with conditional -->
{#if maybeSnippet}
	{@render maybeSnippet()}
{/if}

3. Uso Incorreto de Parênteses na Seleção Dinâmica

Ao selecionar dinamicamente entre snippets—como usar uma expressão ternária—é um erro comum invocar ambos os snippets antes de fazer a seleção. Isso pode levar a comportamentos inesperados ou erros.

Boa Prática: Envolva sua seleção em parênteses antes de invocar: (condition ? snippetA : snippetB)()

<!-- AVOID: Calls both snippets before selecting -->
{@render condition ? snippetA() : snippetB()}

<!-- PREFERRED: Selects snippet first, then invokes -->
{@render (condition ? snippetA : snippetB)()}

4. Esperar que Snippets Retornem Valores

Snippets são projetados exclusivamente para renderizar UI e não retornam valores que possam ser usados em expressões JavaScript ou atribuídos a variáveis. Eles produzem elementos DOM dentro do contexto do template.

Lembre-se: Snippets produzem DOM, não dados. Use-os para renderizar UI dentro do seu template—nunca espere que retornem valores para uso em expressões JavaScript.

<!-- AVOID: This doesn't work -->
<script>
	let result = someSnippet() // Snippets don't return values
</script>

<!-- PREFERRED:Snippets are rendered in templates -->
{@render someSnippet()}

5. Uso Excessivo de Snippets Grandes ou Complexos

Embora snippets sejam poderosos, usá-los excessivamente para conteúdo grande ou profundamente aninhado pode tornar seu código mais difícil de ler, manter e otimizar. Snippets grandes se tornam monolíticos, misturando múltiplas responsabilidades e dificultando o raciocínio sobre atualizações ou reutilização de partes da sua UI.

Exemplo de um snippet excessivamente complexo:

{#snippet dashboard(user, stats, notifications)}
	<section class="dashboard">
		<header>
			<h1>Welcome, {user.name}</h1>
			<span>{stats.points} points</span>
		</header>
		<main>
			<div class="stats">
				<!-- lots of markup and logic here -->
			</div>
			<div class="notifications">
				{#each notifications as note}
					<div class="note">{note.message}</div>
				{/each}
			</div>
			<!-- more nested content -->
		</main>
		<footer>
			<!-- more markup -->
		</footer>
	</section>
{/snippet}

Melhor abordagem: Divida snippets grandes em snippets menores e focados:

{#snippet dashboardHeader(user, stats)}
	<header>
		<h1>Welcome, {user.name}</h1>
		<span>{stats.points} points</span>
	</header>
{/snippet}

{#snippet dashboardNotifications(notifications)}
	<div class="notifications">
		{#each notifications as note}
			<div class="note">{note.message}</div>
		{/each}
	</div>
{/snippet}

{#snippet dashboard(user, stats, notifications)}
	<section class="dashboard">
		{@render dashboardHeader(user, stats)}
		<main>
			{@render dashboardNotifications(notifications)}
		</main>
	</section>
{/snippet}

Dica: Prefira snippets pequenos e de propósito único e componha-os para UIs complexas. Isso melhora a legibilidade, a manutenibilidade e o desempenho.

Considerações de Desempenho

Embora a tag @render seja altamente flexível e habilite padrões poderosos de composição, é importante estar atento ao desempenho ao usar snippets extensivamente. Cada invocação de @render cria novos nós DOM, e re-renderizações desnecessárias podem impactar a responsividade—especialmente em UIs grandes ou dinâmicas.

Tags de renderização são leves—essencialmente chamadas de função que produzem DOM. No entanto:

Cada @render produz novos nós DOM. Se um snippet é custoso e renderizado frequentemente, certifique-se de que as re-renderizações são necessárias.
Use #key para atualizações controladas quando quiser forçar a recriação:

{#key data.id}
	{@render expensiveSnippet(data)}
{/key}

Mantenha snippets focados. Snippets monolíticos grandes são mais difíceis de otimizar do que snippets pequenos e compostos.
Evite invocações desnecessárias de snippets em loops. Ao renderizar centenas de itens, certifique-se de que a lógica do snippet seja mínima:

<!-- Better: Pre-compute outside the loop -->
<script>
	let itemsWithMetadata = $derived(
		items.map((item) => ({
			...item,
			formattedDate: formatDate(item.date),
			isExpired: Date.now() > item.expiryTime
		}))
	)
</script>

<!-- Less optimal: Complex logic in snippet -->
{#snippet itemCard(item)}
	<div>
		{@const formattedDate = formatDate(item.date)}
		{@const isExpired = Date.now() > item.expiryTime}
		<!-- ... complex rendering ... -->
	</div>
{/snippet}

{#each itemsWithMetadata as item}
	{@render itemCard(item)}
{/each}

Considerações de Acessibilidade

Ao usar @render para conteúdo dinâmico ou opcional, certifique-se de que seus snippets renderizados mantenham acessibilidade adequada:

Roles e Labels ARIA

Sempre defina atributos ARIA apropriados dentro dos seus snippets:

{#snippet accessibleButton(label, action)}
	<button type="button" aria-label={label} onclick={action}>
		{label}
	</button>
{/snippet}

{@render accessibleButton('Close dialog', closeDialog)}

Gerenciamento de Foco

Para modais e conteúdo dinâmico, gerencie o foco adequadamente:

<!-- Modal.svelte -->
<script>
	let { isOpen = $bindable(false), children } = $props()
	let dialogEl = $state(null)

	$effect(() => {
		if (isOpen && dialogEl) {
			dialogEl.showModal()
			// Focus first focusable element
			const firstFocusable = dialogEl.querySelector(
				'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
			)
			firstFocusable?.focus()
		}
	})
</script>

Anúncios para Leitores de Tela

Use regiões ao vivo para conteúdo dinâmico:

{#snippet loadingStatus(loading)}
	<div aria-live="polite" aria-busy={loading}>
		{#if loading}
			Loading content...
		{/if}
	</div>
{/snippet}

Considerações sobre SSR (Renderização do Lado do Servidor)

A tag @render funciona perfeitamente com o SSR do SvelteKit. No entanto, se seus snippets dependem de APIs exclusivas do navegador, proteja esses usos para evitar erros de hidratação:

<script>
	import { browser } from '$app/environment'

	let windowWidth = $state(browser ? window.innerWidth : 0)
</script>

{#snippet clientOnly()}
	{#if browser}
		<p>Window width: {windowWidth}px</p>
	{/if}
{/snippet}

{@render clientOnly()}

Boa Prática: Mova chamadas de API do navegador para blocos $effect ou use a verificação browser do SvelteKit:

<script>
	import { browser } from '$app/environment'

	let data = $state(null)

	$effect(() => {
		if (browser) {
			data = localStorage.getItem('key')
		}
	})
</script>

Referência Rápida

<!-- Basic invocation -->
{@render snippetName()}

<!-- With arguments -->
{@render snippetName(arg1, arg2)}

<!-- Optional (safe if undefined) -->
{@render snippetName?.()}

<!-- Conditional with fallback -->
{#if snippetName}
	{@render snippetName()}
{:else}
	<p>Fallback content</p>
{/if}

<!-- Dynamic selection -->
{@render (condition ? snippetA : snippetB)()}

<!-- Children snippet -->
{@render children?.()}

<!-- Children with data -->
{@render children?.({ loading, error, data })}

<!-- With $derived -->
{@render (hasResults ? resultList : emptyState)(filteredData)}

Solução de Problemas

Erro: "Cannot read properties of undefined (reading 'call')"

Isso geralmente significa que você tentou renderizar um snippet indefinido
Solução: Use encadeamento opcional: {@render maybeSnippet?.()}

Nada é renderizado

Você esqueceu de invocar o snippet com ()?
Sempre use parênteses: {@render mySnippet()}

Incompatibilidade de hidratação no SvelteKit

Se você usar APIs exclusivas do navegador em snippets, envolva-as em $effect ou verifique browser
Importe browser de $app/environment e proteja seu código

Props não reativas

Certifique-se de usar as runes do Svelte 5 ($state, $derived, $effect) para reatividade
Verifique se os componentes pai também estão usando runes corretamente

Problemas de desempenho com muitas renderizações

Pré-compute dados com $derived antes de passá-los para snippets
Mantenha snippets pequenos e focados
Use blocos #key criteriosamente para atualizações controladas

Conclusão

A tag {@render} transforma o modelo de templates do Svelte ao tratar fragmentos de UI como valores de primeira classe que podem ser passados, armazenados e invocados programaticamente. Essa mudança de paradigma, de slots para snippets com renderização explícita, oferece controle sem precedentes sobre padrões de composição de componentes. Seja construindo bibliotecas de componentes com renderização personalizável, implementando layouts condicionais complexos ou criando estruturas de dados recursivas, {@render} fornece a base para APIs de componentes flexíveis e de fácil manutenção.

Dominar {@render} significa entender não apenas a sintaxe, mas os padrões arquiteturais que ela habilita. A renderização opcional com verificação de nulo se torna trivial. A seleção dinâmica de snippets com base em condições de tempo de execução se torna elegante. Padrões complexos de delegação onde componentes pai controlam a renderização de componentes filho se tornam naturais. Ao combinar {@render} com $derived para seleção computada de snippets e padrões adequados de segurança contra nulo, você pode construir sistemas de componentes que são ao mesmo tempo poderosos e seguros em termos de tipos.

Principais Conclusões

{@render} invoca funções de snippet definidas com #snippet, passando argumentos para parâmetros de snippet para fragmentos de UI dinâmicos e reutilizáveis
A renderização opcional requer verificação de nulo usando {#if snippet} ou encadeamento opcional: {@render snippet?.()} para evitar erros em tempo de execução quando snippets são indefinidos
Argumentos são passados entre parênteses com segurança de tipos: {@render card({ title, description, imageUrl })} passa dados para parâmetros de snippet
A seleção dinâmica de snippets habilita padrões de renderização determinados em tempo de execução, como {@render variants[size]?.()} para APIs de componentes baseadas em variantes
Snippets são reativos - quando as dependências de um snippet mudam, o Svelte re-renderiza automaticamente a saída sem gerenciamento manual de efeitos
Padrões de delegação de componentes permitem que componentes pai controlem a renderização de componentes filho por meio de props de snippet, habilitando composição flexível sem prop drilling
Seguro para SSR por padrão, mas APIs exclusivas do navegador em snippets requerem encapsulamento com $effect ou verificações de ambiente browser para segurança na hidratação
Considerações de desempenho incluem pré-computar dados com $derived antes de passá-los para snippets e manter o escopo dos snippets mínimo para atualizações eficientes

Veja Também

Documentação Oficial do Svelte 5 - {@render}
$props() - Props de componente, incluindo props de snippet
$derived - Computações reativas para lógica de seleção de snippets
Padrões de Composição de Componentes - Design avançado de APIs de componentes
TypeScript com Svelte - Definições de snippets com segurança de tipos

Invocando Snippets com Precisão

Invocação Básica

Renderizando com Argumentos

Snippets Opcionais: Padrões de Renderização Segura

1. Encadeamento Opcional

2. Renderização Condicional com Fallback

Cadeias de Fallback em Cascata

Seleção Dinâmica de Snippets

Seleção com Ternário

Lógica Condicional para Múltiplas Opções

Seleção Baseada em Função

Usando $derived para Seleção Dinâmica

O Padrão de Snippet children

Passando Dados de Volta Através de children

Padrões de Design de API de Componentes

Props de Snippet Explícitos vs Implícitos

Componente Flexível com Múltiplos Pontos de Renderização

Padrões do Mundo Real

1. Composição de Layout

2. Padrão Modal/Dialog

3. Padrão de Componente de Abas

4. Padrão de Estado de Carregamento

5. Sistema de Notificações Toast

6. Contêiner de Estado Sem Renderização

7. Renderização Recursiva (Estruturas em Árvore)

Integração com TypeScript

Armadilhas Comuns

1. Esquecer de Invocar o Snippet

2. Renderizando Snippets Indefinidos

3. Uso Incorreto de Parênteses na Seleção Dinâmica

4. Esperar que Snippets Retornem Valores

5. Uso Excessivo de Snippets Grandes ou Complexos

Considerações de Desempenho

Considerações de Acessibilidade

Roles e Labels ARIA

Gerenciamento de Foco

Anúncios para Leitores de Tela

Considerações sobre SSR (Renderização do Lado do Servidor)

Referência Rápida

Solução de Problemas

Conclusão

Principais Conclusões

Veja Também

O Padrão de Snippet `children`