Renderização Declarativa de Listas

No cerne de toda aplicação web dinâmica está a necessidade de renderizar coleções de dados—listas de usuários, catálogos de produtos, feeds de notificações, linhas de tabela, itens de navegação. Embora o JavaScript ofereça Array.prototype.map() para transformar arrays, o bloco #each do Svelte 5 oferece algo muito mais poderoso: um mecanismo declarativo, reativo e altamente otimizado para renderizar listas que se atualiza automaticamente quando seus dados mudam.

Compreender o #each em profundidade não é apenas aprender sintaxe—é entender como o Svelte rastreia elementos do DOM, por que as chaves importam para desempenho e correção, e como aproveitar a desestruturação e padrões para escrever código mais limpo e de fácil manutenção. Este tutorial explora cada faceta da renderização de listas no Svelte 5, desde a iteração básica até padrões avançados que tornarão suas aplicações ao mesmo tempo performáticas e elegantes.

A Base

Sintaxe Básica do Bloco Each

O bloco #each itera sobre qualquer valor que possa ser usado com Array.from()—arrays, objetos semelhantes a arrays (qualquer coisa com uma propriedade length), ou iteráveis como Map e Set.

{#each expression as name}
	<!-- rendered for each item -->
{/each}

Aqui está o exemplo mais simples:

<script>
	let fruits = $state(['Apple', 'Banana', 'Cherry', 'Date'])
</script>

<ul>
	{#each fruits as fruit}
		<li>{fruit}</li>
	{/each}
</ul>

Isso renderiza uma lista não ordenada com quatro itens. Quando fruits muda—itens adicionados, removidos ou modificados—o Svelte atualiza automaticamente o DOM para refletir o novo estado.

Tratando `null` e `undefined`

Se a expressão resultar em null ou undefined, o Svelte a trata como um array vazio. Isso significa que nenhum item é renderizado e qualquer bloco {:else} (abordado mais adiante) será exibido:

<script>
	let items = $state(null)

	async function loadItems() {
		const response = await fetch('/api/items')
		items = await response.json()
	}
</script>

{#each items as item}
	<div>{item.name}</div>
{:else}
	<p>No items to display</p>
{/each}

<!-- Before loadItems() completes, "No items to display" shows -->

Esse comportamento elimina a necessidade de verificações explícitas de nulo nos seus templates.

Acessando o Índice

Muitas vezes você precisa saber a posição de um item dentro da lista. O bloco #each fornece um segundo parâmetro opcional—o índice:

{#each expression as name, index}
	<!-- index is 0-based -->
{/each}

<script>
	let steps = $state(['Create account', 'Verify email', 'Complete profile', 'Start exploring'])
</script>

<ol class="setup-wizard">
	{#each steps as step, i}
		<li class="step">
			<span class="step-number">{i + 1}</span>
			<span class="step-label">{step}</span>
		</li>
	{/each}
</ol>

O índice é equivalente ao segundo argumento em array.map((item, index) => ...). Começa em zero e é atualizado automaticamente quando itens são reordenados, adicionados ou removidos.

Usando o Índice para Estilização Condicional

<script>
	let tableData = $state([
		{ name: 'Alice', role: 'Developer', department: 'Engineering' },
		{ name: 'Bob', role: 'Designer', department: 'Product' },
		{ name: 'Charlie', role: 'Manager', department: 'Operations' },
		{ name: 'Diana', role: 'Analyst', department: 'Finance' }
	])
</script>

<table>
	<thead>
		<tr>
			<th>#</th>
			<th>Name</th>
			<th>Role</th>
			<th>Department</th>
		</tr>
	</thead>
	<tbody>
		{#each tableData as row, index}
			<tr class={{ even: index % 2 === 0, odd: index % 2 === 1 }}>
				<td>{index + 1}</td>
				<td>{row.name}</td>
				<td>{row.role}</td>
				<td>{row.department}</td>
			</tr>
		{/each}
	</tbody>
</table>

<style>
	.even {
		background: #f8fafc;
	}
	.odd {
		background: #ffffff;
	}
</style>

Detecção do Primeiro e Último Item

<script>
	let breadcrumbs = $state([
		{ label: 'Home', href: '/' },
		{ label: 'Products', href: '/products' },
		{ label: 'Electronics', href: '/products/electronics' },
		{ label: 'Laptops', href: '/products/electronics/laptops' }
	])
</script>

<nav aria-label="Breadcrumb">
	<ol class="breadcrumb">
		{#each breadcrumbs as crumb, i}
			{@const isFirst = i === 0}
			{@const isLast = i === breadcrumbs.length - 1}

			<li class={{ first: isFirst, current: isLast }}>
				{#if isLast}
					<span aria-current="page">{crumb.label}</span>
				{:else}
					<a href={crumb.href}>{crumb.label}</a>
					<span class="separator">/</span>
				{/if}
			</li>
		{/each}
	</ol>
</nav>

Blocos Each com Chave

É aqui que o #each se torna verdadeiramente poderoso—e onde muitos desenvolvedores encontram seus primeiros bugs sutis.

{#each expression as name (key)}
	<!-- key uniquely identifies each item -->
{/each}

Por Que as Chaves Importam

Sem uma chave, o Svelte atualiza a lista por índice. Quando os itens mudam, o Svelte compara os arrays antigo e novo posição por posição:

Posição 0: Atualiza se diferente
Posição 1: Atualiza se diferente
E assim por diante...

Isso funciona bem em casos simples, mas falha quando itens são reordenados, inseridos no meio ou removidos de qualquer posição que não seja o final.

O Problema Sem Chaves:

<script>
	let todos = $state([
		{ id: 1, text: 'Learn Svelte', done: false },
		{ id: 2, text: 'Build an app', done: false },
		{ id: 3, text: 'Deploy', done: false }
	])

	function removeFirst() {
		todos = todos.slice(1)
	}
</script>

<!-- WITHOUT key: BUGGY -->
{#each todos as todo}
	<div class="todo">
		<input type="checkbox" bind:checked={todo.done} />
		<span>{todo.text}</span>
	</div>
{/each}

<button onclick={removeFirst}>Remove First</button>

Se você marcar o primeiro checkbox e depois clicar em "Remove First," pode esperar que o primeiro todo desapareça. Mas sem uma chave, o Svelte atualiza por índice:

A posição 0 agora tem "Build an app" → atualiza o texto, mantém o estado do checkbox
A posição 1 agora tem "Deploy" → atualiza o texto, mantém o estado do checkbox
A posição 2 não existe mais → remove o último elemento do DOM

O resultado: O item "Build an app" agora aparece marcado, o que está errado!

A Solução Com Chaves:

{#each todos as todo (todo.id)}
	<div class="todo">
		<input type="checkbox" bind:checked={todo.done} />
		<span>{todo.text}</span>
	</div>
{/each}

Agora o Svelte rastreia cada elemento do DOM pelo seu todo.id. Quando você remove o primeiro todo:

O Svelte percebe que id: 1 desapareceu → remove aquele elemento específico do DOM
Os itens com id: 2 e id: 3 permanecem intocados

O estado do checkbox permanece associado ao item correto.

O Que Torna uma Boa Chave?

As chaves devem identificar de forma única cada item dentro da lista. Boas chaves são:

Únicas: Nenhum dois itens devem ter a mesma chave
Estáveis: O mesmo item deve sempre ter a mesma chave entre renderizações
Simples: Strings e números são preferidos (eles preservam a identidade mesmo quando a referência do objeto muda)

<!-- PREFERRED: Using unique database IDs -->
{#each users as user (user.id)}

<!-- PREFERRED: Using unique slugs or codes -->
{#each products as product (product.sku)}

<!-- PREFERRED: Compound keys when needed -->
{#each orderItems as item (`${item.orderId}-${item.productId}`)}

<!-- RISKY: Using index as key (same as no key for reordering) -->
{#each items as item, i (i)}

<!-- AVOID: Using non-unique values -->
{#each users as user (user.role)}  <!-- Multiple users can share a role! -->

<!-- AVOID: Using object references that change -->
{#each items as item (item)}  <!-- New object reference = new key -->

Chaves com Índice

Você pode usar tanto uma chave quanto um índice juntos:

{#each items as item, index (item.id)}
	<div>
		{index + 1}. {item.name}
	</div>
{/each}

A chave rastreia a identidade do elemento no DOM, enquanto o índice reflete a posição atual.

Quando as Chaves São Essenciais

Sempre use chaves quando:

Itens têm estado interno (inputs de formulário, estado de componente, animações)
Itens podem ser reordenados (arrastar e soltar, ordenação)
Itens podem ser inseridos ou removidos do meio
Usando transições ou animações (o Svelte precisa saber quais elementos animar)
Componentes mantêm seu próprio estado

<script>
	import { flip } from 'svelte/animate'
	import { fade } from 'svelte/transition'

	let items = $state([
		{ id: 1, name: 'Item A' },
		{ id: 2, name: 'Item B' },
		{ id: 3, name: 'Item C' }
	])

	function shuffle() {
		items = items.sort(() => Math.random() - 0.5)
	}
</script>

<button onclick={shuffle}>Shuffle</button>

<ul>
	{#each items as item (item.id)}
		<li animate:flip={{ duration: 300 }} transition:fade>
			{item.name}
		</li>
	{/each}
</ul>

Sem a chave, a animação FLIP não funcionaria corretamente—o Svelte não saberia qual elemento foi movido para onde.

Acesso Mais Limpo às Propriedades dos Itens

O #each do Svelte suporta completamente padrões de desestruturação do JavaScript, permitindo que você extraia propriedades diretamente na declaração do loop.

Desestruturação de Objetos

Problema: Acessar propriedades com user.property em um bloco each pode ser verboso e repetitivo, especialmente com muitas propriedades.

Solução: Use desestruturação de objetos na declaração do #each para acessar propriedades diretamente e tornar seu markup mais limpo.

<script>
	let users = $state([
		{ id: 1, name: 'Alice Chen', email: 'alice@example.com', role: 'Admin' },
		{ id: 2, name: 'Bob Smith', email: 'bob@example.com', role: 'User' },
		{ id: 3, name: 'Carol Davis', email: 'carol@example.com', role: 'Moderator' }
	])
</script>

<!-- Without destructuring -->
{#each users as user (user.id)}
	<div class="user-card">
		<h3>{user.name}</h3>
		<p>{user.email}</p>
		<span class="role">{user.role}</span>
	</div>
{/each}

<!-- With destructuring -->
{#each users as { id, name, email, role } (id)}
	<div class="user-card">
		<h3>{name}</h3>
		<p>{email}</p>
		<span class="role">{role}</span>
	</div>
{/each}

Observe que ao desestruturar, você ainda pode referenciar propriedades desestruturadas na expressão de chave.

Desestruturação Aninhada

Problema: Acessar propriedades profundamente aninhadas (como order.customer.address.city) em um bloco each pode poluir seu markup e dificultar a leitura.

Solução: Use desestruturação aninhada na declaração do #each para extrair valores aninhados diretamente.

<script>
	let orders = $state([
		{
			id: 'ORD-001',
			customer: { name: 'Alice', address: { city: 'Seattle', zip: '98101' } },
			total: 149.99
		},
		{
			id: 'ORD-002',
			customer: { name: 'Bob', address: { city: 'Portland', zip: '97201' } },
			total: 89.5
		}
	])
</script>

{#each orders as { id, customer: { name, address: { city } }, total } (id)}
	<div class="order-row">
		<span class="order-id">{id}</span>
		<span class="customer">{name}</span>
		<span class="city">{city}</span>
		<span class="total">${total.toFixed(2)}</span>
	</div>
{/each}

Desestruturação com Valores Padrão

Problema: Alguns itens do seu array podem ter propriedades ausentes ou opcionais, o que pode resultar em valores undefined na sua marcação.

Solução: Use valores padrão na desestruturação para fornecer alternativas para propriedades ausentes.

<script>
	let notifications = $state([
		{ id: 1, message: 'Welcome!', type: 'info' },
		{ id: 2, message: 'Error occurred' }, // type is missing
		{ id: 3, message: 'Success!', type: 'success' }
	])
</script>

{#each notifications as { id, message, type = 'default' } (id)}
	<div class="notification notification-{type}">
		{message}
	</div>
{/each}

Desestruturação com Índice

Problema: Você quer acessar tanto as propriedades do item quanto o índice atual no loop, mas referenciar ambos pode ser verboso.

Solução: Desestruture tanto o item quanto o índice na declaração #each para um acesso conciso.

{#each items as { id, name, value }, index (id)}
	<div class="item">
		<span class="position">#{index + 1}</span>
		<span class="name">{name}</span>
		<span class="value">{value}</span>
	</div>
{/each}

Blocos Else

Tratando Listas Vazias

A cláusula {:else} é renderizada quando a lista está vazia (ou é null/undefined):

{#each expression as name}
	<!-- items -->
{:else}
	<!-- shown when list is empty -->
{/each}

<script>
	let searchResults = $state([])
	let searchQuery = $state('')
	let hasSearched = $state(false)

	async function search() {
		hasSearched = true
		const response = await fetch(`/api/search?q=${encodeURIComponent(searchQuery)}`)
		searchResults = await response.json()
	}
</script>

<form
	onsubmit={(e) => {
		e.preventDefault()
		search()
	}}
>
	<input bind:value={searchQuery} placeholder="Search..." />
	<button type="submit">Search</button>
</form>

{#each searchResults as result (result.id)}
	<div class="result-item">
		<h3>{result.title}</h3>
		<p>{result.description}</p>
	</div>
{:else}
	{#if hasSearched}
		<div class="no-results">
			<p>No results found for "{searchQuery}"</p>
			<p>Try different keywords or check your spelling.</p>
		</div>
	{:else}
		<div class="search-prompt">
			<p>Enter a search term to find results.</p>
		</div>
	{/if}
{/each}

Componentes de Estado Vazio

Problema: Você quer exibir uma interface de estado vazio amigável e reutilizável quando uma lista está vazia, em vez de apenas texto simples.

Solução: Use o bloco {:else} para renderizar um componente de estado vazio personalizado quando o array está vazio.

<script>
	import EmptyState from './EmptyState.svelte'

	let notifications = $state([])
</script>

<div class="notifications-panel">
	<h2>Notifications</h2>

	{#each notifications as notification (notification.id)}
		<div class="notification notification-{notification.type}">
			<span class="icon">{notification.icon}</span>
			<p>{notification.message}</p>
			<time>{notification.timestamp}</time>
		</div>
	{:else}
		<EmptyState
			icon="🔔"
			title="No notifications"
			message="You're all caught up! Check back later for updates."
		/>
	{/each}
</div>

Iterando Sobre Diferentes Estruturas de Dados

Maps

Problema: Você quer iterar sobre um Map do JavaScript e renderizar tanto a chave quanto o valor para cada entrada.

Solução: Use desestruturação de array no bloco #each para acessar tanto a chave quanto o valor diretamente.

<script>
	let userRoles = $state(
		new Map([
			['alice', 'Admin'],
			['bob', 'Editor'],
			['carol', 'Viewer']
		])
	)
</script>

<ul>
	{#each userRoles as [username, role] (username)}
		<li>
			<strong>{username}</strong>: {role}
		</li>
	{/each}
</ul>

Sets

Problema: Você quer renderizar uma lista de tags únicas de um Set e permitir que os usuários as removam de forma interativa.

Solução: Use um bloco #each para iterar sobre o Set e atualize o Set de forma reativa quando uma tag for removida.

<script>
	let tags = $state(new Set(['svelte', 'javascript', 'frontend', 'web']))

	function removeTag(tag) {
		tags.delete(tag)
		tags = new Set(tags) // Trigger reactivity
	}
</script>

<div class="tag-list">
	{#each tags as tag (tag)}
		<span class="tag">
			{tag}
			<button onclick={() => removeTag(tag)}>×</button>
		</span>
	{/each}
</div>

Entradas de Objeto

Problema: Você quer renderizar uma tabela de pares chave-valor de um objeto, permitindo a edição de cada valor, incluindo booleanos.

Solução: Use Object.entries() com um bloco #each para iterar sobre as propriedades do objeto e renderize os controles de entrada apropriados para cada tipo de valor.

<script>
	let config = $state({
		theme: 'dark',
		language: 'en',
		notifications: true,
		autoSave: false
	})
</script>

<table class="config-table">
	<thead>
		<tr>
			<th>Setting</th>
			<th>Value</th>
		</tr>
	</thead>
	<tbody>
		{#each Object.entries(config) as [key, value] (key)}
			<tr>
				<td>{key}</td>
				<td>
					{#if typeof value === 'boolean'}
						<input
							type="checkbox"
							checked={value}
							onchange={(e) => (config[key] = e.target.checked)}
						/>
					{:else}
						<input type="text" {value} oninput={(e) => (config[key] = e.target.value)} />
					{/if}
				</td>
			</tr>
		{/each}
	</tbody>
</table>

Funções Geradoras

Problema: Você quer renderizar uma lista de números gerados por uma função geradora, como a sequência de Fibonacci, e exibi-los na interface.

Solução: Use um gerador para produzir a sequência, converta-a em um array e itere com um bloco #each.

<script>
	function* fibonacci(limit) {
		let a = 0,
			b = 1
		while (a <= limit) {
			yield a
			;[a, b] = [b, a + b]
		}
	}

	let maxValue = $state(100)
	let fibNumbers = $derived([...fibonacci(maxValue)])
</script>

<input type="range" bind:value={maxValue} min="10" max="1000" />
<p>Fibonacci numbers up to {maxValue}:</p>

<div class="number-grid">
	{#each fibNumbers as num, i (i)}
		<span class="fib-number">{num}</span>
	{/each}
</div>

Blocos Each Aninhados

Estruturas de dados complexas frequentemente requerem iterações aninhadas:

<script>
	let departments = $state([
		{
			name: 'Engineering',
			teams: [
				{ name: 'Frontend', members: ['Alice', 'Bob'] },
				{ name: 'Backend', members: ['Carol', 'Dave', 'Eve'] },
				{ name: 'DevOps', members: ['Frank'] }
			]
		},
		{
			name: 'Design',
			teams: [
				{ name: 'UI/UX', members: ['Grace', 'Henry'] },
				{ name: 'Brand', members: ['Ivy'] }
			]
		}
	])
</script>

<div class="org-chart">
	{#each departments as dept (dept.name)}
		<section class="department">
			<h2>{dept.name}</h2>

			{#each dept.teams as team (team.name)}
				<div class="team">
					<h3>{team.name}</h3>

					<ul class="members">
						{#each team.members as member (member)}
							<li>{member}</li>
						{/each}
					</ul>
				</div>
			{/each}
		</section>
	{/each}
</div>

Achatamento com Rastreamento de Índice

Às vezes você precisa manter a consciência de múltiplos níveis de aninhamento:

<script>
	let categories = $state([
		{
			name: 'Electronics',
			products: [
				{ id: 'e1', name: 'Laptop', price: 999 },
				{ id: 'e2', name: 'Phone', price: 699 }
			]
		},
		{
			name: 'Clothing',
			products: [
				{ id: 'c1', name: 'Jacket', price: 149 },
				{ id: 'c2', name: 'Shoes', price: 89 },
				{ id: 'c3', name: 'Hat', price: 29 }
			]
		}
	])
</script>

<table>
	<thead>
		<tr>
			<th>Category</th>
			<th>#</th>
			<th>Product</th>
			<th>Price</th>
		</tr>
	</thead>
	<tbody>
		{#each categories as category, categoryIndex (category.name)}
			{#each category.products as product, productIndex (product.id)}
				<tr>
					{#if productIndex === 0}
						<td rowspan={category.products.length} class="category-cell">
							{category.name}
						</td>
					{/if}
					<td>{productIndex + 1}</td>
					<td>{product.name}</td>
					<td>${product.price}</td>
				</tr>
			{/each}
		{/each}
	</tbody>
</table>

Reatividade e Blocos Each

Entender como o #each interage com o sistema de reatividade do Svelte 5 é fundamental para criar aplicações com bom desempenho.

Arrays Reativos com `$state`

<script>
	let todos = $state([
		{ id: 1, text: 'Learn Svelte', done: false },
		{ id: 2, text: 'Build something', done: false }
	])

	let newTodoText = $state('')

	function addTodo() {
		if (!newTodoText.trim()) return

		todos.push({
			id: Date.now(),
			text: newTodoText,
			done: false
		})
		newTodoText = ''
	}

	function removeTodo(id) {
		const index = todos.findIndex((t) => t.id === id)
		if (index !== -1) {
			todos.splice(index, 1)
		}
	}

	function toggleTodo(id) {
		const todo = todos.find((t) => t.id === id)
		if (todo) {
			todo.done = !todo.done
		}
	}
</script>

<form
	onsubmit={(e) => {
		e.preventDefault()
		addTodo()
	}}
>
	<input bind:value={newTodoText} placeholder="New todo..." />
	<button type="submit">Add</button>
</form>

<ul>
	{#each todos as todo (todo.id)}
		<li class={{ done: todo.done }}>
			<input type="checkbox" checked={todo.done} onchange={() => toggleTodo(todo.id)} />
			<span>{todo.text}</span>
			<button onclick={() => removeTodo(todo.id)}>Delete</button>
		</li>
	{/each}
</ul>

<style>
	.done span {
		text-decoration: line-through;
		opacity: 0.6;
	}
</style>

No Svelte 5, mutações de array como push, splice e atribuições de propriedades são rastreadas automaticamente quando o array é declarado com $state.

Listas Derivadas com `$derived`

<script>
	let products = $state([
		{ id: 1, name: 'Laptop', price: 999, category: 'electronics', inStock: true },
		{ id: 2, name: 'Mouse', price: 29, category: 'electronics', inStock: true },
		{ id: 3, name: 'Notebook', price: 5, category: 'office', inStock: false },
		{ id: 4, name: 'Keyboard', price: 79, category: 'electronics', inStock: true },
		{ id: 5, name: 'Pen', price: 2, category: 'office', inStock: true }
	])

	let categoryFilter = $state('all')
	let showInStockOnly = $state(false)
	let sortBy = $state('name')
	let sortOrder = $state('asc')

	let filteredProducts = $derived.by(() => {
		let result = products

		// Filter by category
		if (categoryFilter !== 'all') {
			result = result.filter((p) => p.category === categoryFilter)
		}

		// Filter by stock
		if (showInStockOnly) {
			result = result.filter((p) => p.inStock)
		}

		// Sort
		result = [...result].sort((a, b) => {
			let aVal = a[sortBy]
			let bVal = b[sortBy]

			if (typeof aVal === 'string') {
				return sortOrder === 'asc' ? aVal.localeCompare(bVal) : bVal.localeCompare(aVal)
			}
			return sortOrder === 'asc' ? aVal - bVal : bVal - aVal
		})

		return result
	})

	let categories = $derived([...new Set(products.map((p) => p.category))])
</script>

<div class="filters">
	<select bind:value={categoryFilter}>
		<option value="all">All Categories</option>
		{#each categories as category (category)}
			<option value={category}>{category}</option>
		{/each}
	</select>

	<label>
		<input type="checkbox" bind:checked={showInStockOnly} />
		In stock only
	</label>

	<select bind:value={sortBy}>
		<option value="name">Sort by Name</option>
		<option value="price">Sort by Price</option>
	</select>

	<button onclick={() => (sortOrder = sortOrder === 'asc' ? 'desc' : 'asc')}>
		{sortOrder === 'asc' ? '↑' : '↓'}
	</button>
</div>

<p>{filteredProducts.length} of {products.length} products</p>

<div class="product-grid">
	{#each filteredProducts as product (product.id)}
		<div class={['product-card', !product.inStock && 'out-of-stock']}>
			<h3>{product.name}</h3>
			<p class="price">${product.price}</p>
			<span class="category">{product.category}</span>
			{#if !product.inStock}
				<span class="badge">Out of Stock</span>
			{/if}
		</div>
	{:else}
		<p class="no-results">No products match your filters.</p>
	{/each}
</div>

Animações e Transições

O bloco #each se integra perfeitamente ao sistema de animações do Svelte.

Transições de Entrada e Saída

<script>
	import { fade, fly, slide } from 'svelte/transition'

	let items = $state([
		{ id: 1, text: 'First item' },
		{ id: 2, text: 'Second item' },
		{ id: 3, text: 'Third item' }
	])

	function addItem() {
		items.push({
			id: Date.now(),
			text: `Item ${items.length + 1}`
		})
	}

	function removeItem(id) {
		const index = items.findIndex((i) => i.id === id)
		if (index !== -1) items.splice(index, 1)
	}
</script>

<button onclick={addItem}>Add Item</button>

<ul>
	{#each items as item (item.id)}
		<li transition:slide={{ duration: 300 }}>
			<span>{item.text}</span>
			<button onclick={() => removeItem(item.id)}>Remove</button>
		</li>
	{/each}
</ul>

Animações FLIP para Reordenação

A diretiva animate:flip cria animações suaves quando itens da lista mudam de posição:

<script>
	import { flip } from 'svelte/animate'
	import { quintOut } from 'svelte/easing'

	let items = $state([
		{ id: 1, name: 'Apple', votes: 0 },
		{ id: 2, name: 'Banana', votes: 0 },
		{ id: 3, name: 'Cherry', votes: 0 },
		{ id: 4, name: 'Date', votes: 0 }
	])

	// Sort by votes (highest first) whenever votes change
	let sortedItems = $derived([...items].sort((a, b) => b.votes - a.votes))

	function vote(id) {
		const item = items.find((i) => i.id === id)
		if (item) item.votes++
	}
</script>

<p>Click to vote! Items reorder by popularity.</p>

<ul class="voting-list">
	{#each sortedItems as item (item.id)}
		<li animate:flip={{ duration: 400, easing: quintOut }}>
			<button onclick={() => vote(item.id)}>
				<span class="name">{item.name}</span>
				<span class="votes">{item.votes} votes</span>
			</button>
		</li>
	{/each}
</ul>

<style>
	.voting-list {
		list-style: none;
		padding: 0;
	}

	.voting-list li {
		margin: 0.5rem 0;
	}

	.voting-list button {
		width: 100%;
		padding: 1rem;
		display: flex;
		justify-content: space-between;
		background: #f8fafc;
		border: 1px solid #e2e8f0;
		border-radius: 8px;
		cursor: pointer;
		transition: background 0.2s;
	}

	.voting-list button:hover {
		background: #e2e8f0;
	}
</style>

Combinando Transições e Animações

<script>
	import { flip } from 'svelte/animate'
	import { fade, scale } from 'svelte/transition'

	let items = $state([
		{ id: 1, text: 'Item A' },
		{ id: 2, text: 'Item B' },
		{ id: 3, text: 'Item C' }
	])

	function shuffle() {
		items = items.sort(() => Math.random() - 0.5)
	}

	function addItem() {
		items.push({ id: Date.now(), text: `Item ${items.length + 1}` })
	}

	function removeItem(id) {
		const index = items.findIndex((i) => i.id === id)
		if (index !== -1) items.splice(index, 1)
	}
</script>

<div class="controls">
	<button onclick={addItem}>Add</button>
	<button onclick={shuffle}>Shuffle</button>
</div>

<ul>
	{#each items as item (item.id)}
		<li
			animate:flip={{ duration: 300 }}
			in:scale={{ duration: 200, start: 0.8 }}
			out:fade={{ duration: 150 }}
		>
			<span>{item.text}</span>
			<button onclick={() => removeItem(item.id)}>×</button>
		</li>
	{/each}
</ul>

Problemas Comuns e Soluções

1: Itens Não Atualizando Corretamente

Problema: Você modifica a propriedade de um item, mas a interface não atualiza.

<script>
	// AVOID: This might not update correctly in older patterns
	let items = [{ id: 1, count: 0 }]

	function increment(id) {
		const item = items.find((i) => i.id === id)
		item.count++ // Direct mutation
	}
</script>

Solução: Use $state para reatividade automática:

<script>
	// PREFERRED: With $state, mutations are tracked
	let items = $state([{ id: 1, count: 0 }])

	function increment(id) {
		const item = items.find((i) => i.id === id)
		if (item) item.count++
	}
</script>

2: Problemas com Chaves em Objetos

Problema: Usar o próprio objeto como chave causa re-renderizações desnecessárias.

<!-- AVOID: Using object - references change, causing all items to re-render -->
{#each items as item (item)}
	<Component data={item} />
{/each}

Solução: Use um identificador estável e único:

<!-- PREFERRED: Stable key -->
{#each items as item (item.id)}
	<Component data={item} />
{/each}

3: Perda de Estado do Componente ao Reordenar

Problema: A reordenação por arrastar e soltar redefine o estado interno do componente.

Causa: Chaves ausentes ou incorretas fazem com que o Svelte recrie os componentes em vez de movê-los.

Solução: Sempre use chaves únicas e estáveis com componentes filhos com estado:

<script>
	import EditableCard from './EditableCard.svelte'

	let cards = $state([
		{ id: 'card-1', title: 'First' },
		{ id: 'card-2', title: 'Second' },
		{ id: 'card-3', title: 'Third' }
	])
</script>

{#each cards as card (card.id)}
	<!-- EditableCard maintains its own editing state -->
	<!-- The key ensures it's preserved across reorders -->
	<EditableCard data={card} />
{/each}

4: Desempenho com Listas Grandes

Problema: Renderizar milhares de itens causa uma interface lenta.

Solução 1: Rolagem virtual (renderizar apenas os itens visíveis):

<script>
	let items = $state(
		Array.from({ length: 10000 }, (_, i) => ({
			id: i,
			text: `Item ${i + 1}`
		}))
	)

	let containerHeight = 400
	let itemHeight = 40
	let scrollTop = $state(0)

	let visibleItems = $derived.by(() => {
		const startIndex = Math.floor(scrollTop / itemHeight)
		const visibleCount = Math.ceil(containerHeight / itemHeight) + 1
		const endIndex = Math.min(startIndex + visibleCount, items.length)

		return items.slice(startIndex, endIndex).map((item, i) => ({
			...item,
			offset: (startIndex + i) * itemHeight
		}))
	})

	let totalHeight = $derived(items.length * itemHeight)
</script>

<div
	class="virtual-list"
	style="height: {containerHeight}px"
	onscroll={(e) => (scrollTop = e.target.scrollTop)}
>
	<div class="spacer" style="height: {totalHeight}px">
		{#each visibleItems as item (item.id)}
			<div class="item" style="position: absolute; top: {item.offset}px; height: {itemHeight}px">
				{item.text}
			</div>
		{/each}
	</div>
</div>

<style>
	.virtual-list {
		overflow-y: auto;
		position: relative;
	}
	.spacer {
		position: relative;
	}
	.item {
		width: 100%;
		display: flex;
		align-items: center;
		padding: 0 1rem;
		box-sizing: border-box;
	}
</style>

Solução 2: Paginação:

<script>
	let allItems = $state([
		/* large array */
	])
	let page = $state(1)
	let pageSize = 20

	let paginatedItems = $derived(allItems.slice((page - 1) * pageSize, page * pageSize))

	let totalPages = $derived(Math.ceil(allItems.length / pageSize))
</script>

{#each paginatedItems as item (item.id)}
	<div>{item.name}</div>
{/each}

<div class="pagination">
	<button disabled={page === 1} onclick={() => page--}>Previous</button>
	<span>Page {page} of {totalPages}</span>
	<button disabled={page === totalPages} onclick={() => page++}>Next</button>
</div>

5: Aviso de Chaves Duplicadas

Problema: O console exibe avisos de "chave duplicada".

Causa: Dois ou mais itens possuem o mesmo valor de chave.

Solução: Certifique-se de que as chaves sejam verdadeiramente únicas, ou crie chaves compostas:

<script>
	// If items from different sources might have same IDs:
	let itemsFromSourceA = $state([{ id: 1, name: 'A1' }])
	let itemsFromSourceB = $state([{ id: 1, name: 'B1' }]) // Same ID!

	let allItems = $derived([
		...itemsFromSourceA.map((i) => ({ ...i, source: 'A' })),
		...itemsFromSourceB.map((i) => ({ ...i, source: 'B' }))
	])
</script>

<!-- Use compound key -->
{#each allItems as item (`${item.source}-${item.id}`)}
	<div>{item.name}</div>
{/each}

6: Dados Assíncronos em Listas

Problema: Cada item precisa buscar dados adicionais.

Solução: Use {#await} dentro do #each:

<script>
	let userIds = $state([1, 2, 3, 4, 5])

	async function fetchUser(id) {
		const response = await fetch(`/api/users/${id}`)
		return response.json()
	}
</script>

<ul>
	{#each userIds as userId (userId)}
		<li>
			{#await fetchUser(userId)}
				<span class="loading">Loading user {userId}...</span>
			{:then user}
				<span>{user.name} - {user.email}</span>
			{:catch error}
				<span class="error">Failed to load user {userId}</span>
			{/await}
		</li>
	{/each}
</ul>

Resumo de Boas Práticas

Sempre use chaves para listas com elementos com estado, reordenação ou animações. A única exceção são listas verdadeiramente estáticas que nunca mudam.
Use identificadores estáveis e únicos como chaves — IDs de banco de dados, UUIDs ou slugs únicos. Evite usar índices de array, exceto para dados verdadeiramente estáticos.
Aproveite a desestruturação para deixar os templates mais limpos e legíveis. Extraia apenas o que você precisa.
Use $derived para listas filtradas, ordenadas ou transformadas. Mantenha a lógica de transformação na seção de script, não no template.
Combine com {:else} para lidar com estados vazios de forma elegante. Nunca deixe os usuários verem uma tela em branco.
Use {@const} dentro de blocos each para valores calculados específicos por item.
Considere o desempenho para listas grandes. Implemente rolagem virtual ou paginação ao lidar com centenas ou milhares de itens.
Teste o comportamento de reordenação ao usar componentes filhos com estado. Certifique-se de que as chaves estejam configuradas corretamente.
Use animações FLIP (animate:flip) para efeitos de reordenação suaves.
Trate dados assíncronos de forma adequada — busque todos os dados antes de renderizar, ou use {#await} por item com estados de carregamento apropriados.

Referência Rápida

<!-- Basic iteration -->
{#each items as item}
	<div>{item.name}</div>
{/each}

<!-- With index -->
{#each items as item, index}
	<div>{index + 1}. {item.name}</div>
{/each}

<!-- With key (recommended for dynamic lists) -->
{#each items as item (item.id)}
	<div>{item.name}</div>
{/each}

<!-- Key with index -->
{#each items as item, index (item.id)}
	<div>{index}: {item.name}</div>
{/each}

<!-- Object destructuring -->
{#each items as { id, name, value } (id)}
	<div>{name}: {value}</div>
{/each}

<!-- Array destructuring -->
{#each coordinates as [x, y] (x + '-' + y)}
	<div>({x}, {y})</div>
{/each}

<!-- Rest pattern -->
{#each items as { id, ...rest } (id)}
	<Component {...rest} />
{/each}

<!-- Without item (repeat N times) -->
{#each { length: 5 } as, i}
	<div>Item {i + 1}</div>
{/each}

<!-- With else block -->
{#each items as item (item.id)}
	<div>{item.name}</div>
{:else}
	<p>No items found.</p>
{/each}

<!-- With animations -->
{#each items as item (item.id)}
	<div animate:flip={{ duration: 300 }} transition:fade>
		{item.name}
	</div>
{/each}

<!-- Nested each blocks -->
{#each categories as category (category.id)}
	<section>
		<h2>{category.name}</h2>
		{#each category.items as item (item.id)}
			<div>{item.name}</div>
		{/each}
	</section>
{/each}

Conclusão

O bloco #each é enganosamente simples em sua forma básica, mas dominar suas nuances — chaves, desestruturação, reatividade, animações — desbloqueia a capacidade de construir interfaces de usuário sofisticadas, eficientes e de fácil manutenção. Entender por que as chaves importam, quando usar estado derivado e como lidar com casos extremos será muito útil à medida que você constrói aplicações Svelte cada vez mais complexas. Esse bloco de construção fundamental transforma arrays de dados brutos em componentes de interface interativos, animados e reativos com eficiência notável.

O verdadeiro poder do #each emerge quando combinado com o ecossistema do Svelte: $derived para transformações de listas, @const para cálculos por item, bind: para arrays de formulários e animate: para reordenação suave. Ao compreender o modelo de reatividade — que #each responde a reatribuições de array, não a mutações — e implementar estratégias adequadas de chaveamento, você pode construir interfaces de lista que são ao mesmo tempo eficientes e de fácil manutenção. Seja renderizando listas simples ou hierarquias aninhadas complexas, #each fornece a base para interfaces orientadas a dados.

Principais Conclusões

Blocos #each iteram arrays de forma reativa, respondendo tanto a mutações diretas (como push, splice, atribuições de propriedades) quanto a reatribuições quando declarados com $state — a reatividade baseada em proxy do Svelte 5 rastreia todas as alterações automaticamente
Expressões de chave são críticas para o desempenho - use identificadores únicos como (item.id) para habilitar a comparação eficiente do DOM e evitar confusões de estado durante a reordenação
A desestruturação simplifica o acesso aos itens com #each items as { id, name, price } extraindo propriedades diretamente, e as item, index fornecendo índices posicionais baseados em zero
Blocos {:else} tratam arrays vazios de forma elegante, renderizando uma interface de fallback quando items.length === 0 sem lógica condicional separada
O parâmetro de índice é baseado em zero e reativo - atualiza automaticamente quando itens são adicionados/removidos, mas evite usá-lo como chave para itens que podem ser reordenados
@const com escopo de bloco permite cálculos por item como {@const total = price * quantity} sem poluir o script do componente com lógica de apresentação
Animações requerem a diretiva animate: com expressões de chave - animate:flip reposiciona os itens suavemente durante a reordenação, exigindo chaves únicas para rastrear o movimento
Blocos #each aninhados suportam dados hierárquicos como árvores ou listas agrupadas, com cada nível mantendo contexto de iteração independente e espaços de chave

Veja Também

Documentação Oficial do Svelte 5 - {#each}
Animações do Svelte - animate: - A animação flip para reordenação suave
$derived - Transformações reativas de listas (filtragem, ordenação, mapeamento)
Transições do Svelte - Animações de entrada/saída para itens de lista
MDN - Métodos de Array - Técnicas de manipulação de arrays em JavaScript