Controle do Ciclo de Vida de Componentes e Recriação Estratégica do DOM

No cenário dos frameworks reativos modernos, um dos desafios mais sutis que os desenvolvedores enfrentam é controlar com precisão quando e como elementos DOM e componentes devem ser recriados em vez de simplesmente atualizados. O bloco {#key ...} do Svelte 5 oferece uma solução elegante para esse problema—um mecanismo declarativo que instrui o compilador a destruir e recriar seu conteúdo sempre que uma expressão especificada muda de valor.

Embora o conceito pareça enganosamente simples à primeira vista, dominar o bloco {#key ...} requer uma compreensão profunda do modelo de reatividade do Svelte, da mecânica do ciclo de vida dos componentes e da interação sutil entre atualizações do DOM e execução do JavaScript. Este tutorial irá guiá-lo por todo o espectro de uso do {#key ...}, desde conceitos fundamentais até padrões arquiteturais avançados que podem transformar a forma como você aborda o design de componentes.

Entendendo o Problema Fundamental: Atualizações vs. Recriação

Antes de mergulhar na sintaxe e na mecânica do {#key ...}, é essencial entender o problema que ele resolve. O sistema de reatividade do Svelte é notavelmente eficiente—quando o estado muda, o Svelte atualiza cirurgicamente apenas as partes do DOM que dependem daquele estado. Essa abordagem granular minimiza a manipulação do DOM e entrega excelente desempenho.

No entanto, essa eficiência cria um desafio: às vezes você não quer atualizações granulares. Às vezes você precisa destruir e recriar completamente um trecho do DOM ou uma instância de componente. Considere estes cenários:

Cenário 1: Redefinindo o Estado Interno de um Componente Imagine um componente de formulário que mantém seu próprio estado interno de validação, rastreamento de campos tocados e mensagens de erro. Quando o usuário alterna de editar o "Usuário A" para o "Usuário B", você quer um formulário completamente novo—não um que carregue os erros de validação do usuário anterior.

Cenário 2: Disparando Animações em Mudanças de Dados Você tem um componente de notificação com uma animação de entrada. Quando uma nova notificação chega, você quer que a animação seja reproduzida novamente. Mas como o Svelte atualiza eficientemente o conteúdo de texto do nó DOM existente, a animação nunca é acionada novamente.

Cenário 3: Integração com Bibliotecas de Terceiros Você está integrando uma biblioteca de gráficos que é inicializada uma vez em onMount e não suporta atualizações reativas. Quando sua fonte de dados muda, você precisa destruir a instância antiga do gráfico e criar uma nova.

O bloco {#key ...} resolve elegantemente todos esses cenários ao fornecer controle explícito sobre o ciclo de vida de destruição/criação.

A Anatomia do `{#key ...}`

Sintaxe e Semântica

A sintaxe básica do bloco {#key ...} é direta:

{#key expression}
	<!-- Content to be destroyed and recreated when expression changes -->
{/key}

A expression pode ser qualquer expressão JavaScript que o Svelte consiga rastrear de forma reativa. Quando o valor dessa expressão muda (usando a comparação de igualdade estrita do JavaScript), o Svelte realiza a seguinte sequência:

Fase de Destruição: Todos os elementos DOM dentro do bloco são removidos. Quaisquer componentes são destruídos, acionando seus callbacks onDestroy. Quaisquer transições em execução completam sua fase de saída.
Fase de Criação: Novos elementos DOM são criados do zero. Os componentes são instanciados novamente, acionando seu código de inicialização e os callbacks onMount. As transições de entrada começam a ser reproduzidas.

Esse ciclo de destruição-então-criação é fundamentalmente diferente do comportamento normal de atualização do Svelte, onde os nós DOM existentes são modificados no lugar.

Uma Demonstração Simples

Vamos começar com um exemplo fundamental que ilustra o comportamento central:

<script>
	import { onMount, onDestroy } from 'svelte'
	import LifecycleTracker from '$lib/components/custom/LifecycleTracker.svelte'

	let userId = $state(1)
	let mountCount = $state(0)
	let destroyCount = $state(0)

	// This component will be recreated when userId changes
</script>

// +page.svelte
{#key userId}
	{@const componentId = Math.random().toString(36).slice(2, 8)}
	<div class="user-panel">
		<LifecycleTracker
			{userId}
			{componentId}
			onMounted={() => mountCount++}
			onDestroyed={() => destroyCount++}
		/>
	</div>
{/key}

<div class="controls">
	<button onclick={() => userId++}>
		Switch to User {userId + 1}
	</button>
	<p>Mount events: {mountCount} | Destroy events: {destroyCount}</p>
</div>

<!-- LifecycleTracker.svelte -->
<script>
	import { onMount, onDestroy } from 'svelte'

	let { userId, componentId, onMounted, onDestroyed } = $props()

	let internalState = $state({
		initialized: false,
		timestamp: null
	})

	onMount(() => {
		internalState.initialized = true
		internalState.timestamp = new Date().toISOString()
		onMounted?.()
		console.log(`[${componentId}] Mounted for user ${userId}`)
	})

	onDestroy(() => {
		onDestroyed?.()
		console.log(`[${componentId}] Destroyed (was user ${userId})`)
	})
</script>

<div class="tracker">
	<p>Component ID: <code>{componentId}</code></p>
	<p>Viewing User: {userId}</p>
	<p>Initialized: {internalState.initialized ? '✓' : '✗'}</p>
	<p>Mount Time: {internalState.timestamp ?? 'Not yet'}</p>
</div>

Cada vez que você clica no botão, observe que:

O componentId muda (provando que uma nova instância foi criada)
O callback onDestroy é acionado antes do novo onMount
O internalState é completamente redefinido—o novo componente não tem conhecimento algum do estado da instância anterior

Esse comportamento é determinístico e previsível, o que é crucial para criar aplicações confiáveis.

Análise Aprofundada

`#key` com Transições

Uma das aplicações mais poderosas do #key é controlar a reprodução de transições. O sistema de transições do Svelte está intimamente conectado à criação e destruição de elementos—as transições são reproduzidas quando elementos entram ou saem do DOM. O bloco #key oferece controle preciso sobre quando esses eventos de ciclo de vida ocorrem.

O Problema de Temporização das Transições

Considere este cenário comum sem #key:

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

	let message = $state('Hello, World!')
	let messages = ['Hello, World!', 'Welcome back!', 'How are you?']
	let index = $state(0)

	function nextMessage() {
		index = (index + 1) % messages.length
		message = messages[index]
	}
</script>

<p transition:fade>{message}</p>

<button onclick={nextMessage}>Next Message</button>

Neste código, a transição nunca é reproduzida após a renderização inicial. Por quê? Porque o Svelte atualiza eficientemente o conteúdo de texto do elemento <p> existente em vez de destruí-lo e recriá-lo. O elemento nunca sai ou entra no DOM, portanto nenhuma transição é acionada.

A Solução com `#key`

Envolver o elemento em um bloco #key resolve isso de forma elegante:

<script>
	import { fade, fly, scale } from 'svelte/transition'
	import { quintOut, elasticOut } from 'svelte/easing'

	let message = $state('Hello, World!')
	let messages = ['Hello, World!', 'Welcome back!', 'How are you?']
	let index = $state(0)

	function nextMessage() {
		index = (index + 1) % messages.length
		message = messages[index]
	}
</script>

{#key message}
	<p
		transition:fly={{
			y: -20,
			duration: 400,
			easing: quintOut
		}}
	>
		{message}
	</p>
{/key}

<button onclick={nextMessage}>Next Message</button>

Agora cada mudança de mensagem aciona uma recriação completa do elemento <p>, e a transição é reproduzida todas as vezes. O elemento antigo voa para fora enquanto o novo elemento voa para dentro.

Orquestração Avançada de Transições

Para efeitos mais sofisticados, você pode combinar #key com diretivas separadas in: e out::

<script>
	import { fly, fade, scale } from 'svelte/transition'
	import { cubicOut, backOut } from 'svelte/easing'

	let currentSlide = $state(0)
	let direction = $state(1) // 1 = forward, -1 = backward

	let slides = $state([
		{ id: 1, title: 'Introduction', content: 'Welcome to our presentation...' },
		{ id: 2, title: 'Core Concepts', content: 'Let us explore the fundamentals...' },
		{ id: 3, title: 'Advanced Topics', content: 'Now for the deep dive...' },
		{ id: 4, title: 'Conclusion', content: 'In summary, we have learned...' }
	])

	function navigate(delta) {
		direction = delta
		currentSlide = Math.max(0, Math.min(slides.length - 1, currentSlide + delta))
	}

	// Derived values for transition parameters
	let flyDistance = $derived(direction * 300)
</script>

<div class="slideshow-container">
	{#key currentSlide}
		<article
			class="slide"
			in:fly={{
				x: flyDistance,
				duration: 500,
				easing: cubicOut,
				delay: 100
			}}
			out:fly={{
				x: -flyDistance,
				duration: 400,
				easing: cubicOut
			}}
		>
			<h2>{slides[currentSlide].title}</h2>
			<p>{slides[currentSlide].content}</p>
			<span class="slide-number">{currentSlide + 1} / {slides.length}</span>
		</article>
	{/key}
</div>

<nav class="slide-controls">
	<button onclick={() => navigate(-1)} disabled={currentSlide === 0}> ← Previous </button>
	<button onclick={() => navigate(1)} disabled={currentSlide === slides.length - 1}>
		Next →
	</button>
</nav>

<style>
	.slideshow-container {
		position: relative;
		min-height: 200px;
		overflow: hidden;
	}

	.slide {
		position: absolute;
		width: 100%;
		padding: 2rem;
		background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
		color: white;
		border-radius: 12px;
	}

	.slide-number {
		position: absolute;
		bottom: 1rem;
		right: 1rem;
		opacity: 0.7;
		font-size: 0.875rem;
	}

	.slide-controls {
		display: flex;
		gap: 1rem;
		margin-top: 1rem;
		justify-content: center;
	}
</style>

Esse padrão cria um slideshow estilo carrossel onde a direção da transição se adapta com base na direção da navegação. O {#key currentSlide} garante que mesmo uma navegação rápida acione corretamente a sequência de animação.

Eventos de Transição com `#key`

As transições do Svelte emitem eventos que você pode capturar para coordenar animações complexas ou acionar efeitos colaterais:

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

	let activePanel = $state('dashboard')
	let isTransitioning = $state(false)
	let transitionPhase = $state('idle')

	let panels = ['dashboard', 'analytics', 'settings', 'profile']

	function handleIntroStart() {
		transitionPhase = 'entering'
		console.log(`Panel "${activePanel}" is entering`)
	}

	function handleIntroEnd() {
		transitionPhase = 'idle'
		isTransitioning = false
		console.log(`Panel "${activePanel}" has fully entered`)
	}

	function handleOutroStart() {
		isTransitioning = true
		transitionPhase = 'leaving'
		console.log(`Previous panel is leaving`)
	}

	function handleOutroEnd() {
		console.log(`Previous panel has been removed`)
	}

	function switchPanel(panel) {
		if (panel !== activePanel && !isTransitioning) {
			activePanel = panel
		}
	}
</script>

<nav class="panel-nav">
	{#each panels as panel}
		<button
			onclick={() => switchPanel(panel)}
			class:active={activePanel === panel}
			disabled={isTransitioning}
		>
			{panel}
		</button>
	{/each}
</nav>

<div class="panel-container">
	<div class="transition-indicator" class:active={isTransitioning}>
		{transitionPhase}
	</div>

	{#key activePanel}
		<section
			class="panel"
			transition:fly={{ y: 30, duration: 300 }}
			onintrostart={handleIntroStart}
			onintroend={handleIntroEnd}
			onoutrostart={handleOutroStart}
			onoutroend={handleOutroEnd}
		>
			<h2>{activePanel}</h2>
			<p>Content for the {activePanel} panel would appear here.</p>
		</section>
	{/key}
</div>

<style>
	.panel-nav {
		display: flex;
		gap: 0.5rem;
		margin-bottom: 1rem;
	}

	.panel-nav button {
		padding: 0.5rem 1rem;
		border: 2px solid #e2e8f0;
		background: white;
		border-radius: 6px;
		cursor: pointer;
		transition: all 0.2s;
	}

	.panel-nav button.active {
		border-color: #667eea;
		background: #667eea;
		color: white;
	}

	.panel-nav button:disabled {
		opacity: 0.5;
		cursor: not-allowed;
	}

	.panel-container {
		position: relative;
		min-height: 150px;
	}

	.transition-indicator {
		position: absolute;
		top: 0.5rem;
		right: 0.5rem;
		padding: 0.25rem 0.5rem;
		background: #f1f5f9;
		border-radius: 4px;
		font-size: 0.75rem;
		text-transform: uppercase;
		opacity: 0;
		transition: opacity 0.2s;
	}

	.transition-indicator.active {
		opacity: 1;
	}

	.panel {
		padding: 1.5rem;
		background: #f8fafc;
		border-radius: 8px;
		border: 1px solid #e2e8f0;
	}
</style>

Esse padrão é inestimável quando você precisa desabilitar interações do usuário durante transições, exibir estados de carregamento ou coordenar múltiplos elementos animados.

Reinstanciação de Componentes

A Opção Nuclear

Quando #key envolve um componente, todo o ciclo de vida do componente é redefinido. Isso é ao mesmo tempo poderoso e potencialmente perigoso—é a "opção nuclear" para o gerenciamento de estado.

Entendendo o que é Redefinido

Quando um componente dentro de #key é recriado:

Todo $state interno é redefinido para os valores iniciais
Todos os valores $derived são recalculados do zero
Todos os blocos $effect executam seu código de configuração novamente
Os callbacks onMount são acionados como se o componente tivesse acabado de ser adicionado à página
Qualquer limpeza onDestroy da instância anterior é executada primeiro
Os valores vinculados são ressincronizados com os novos elementos DOM
O contexto é herdado novamente dos componentes pai (embora os próprios valores de contexto possam ser as mesmas referências)

<!-- StatefulWidget.svelte -->
<script>
	import { onMount, onDestroy } from 'svelte'
	import { getContext } from 'svelte'

	let { widgetId } = $props()

	// All of this state resets on recreation
	let clickCount = $state(0)
	let lastInteraction = $state(null)
	let computedValue = $derived(clickCount * 2)

	// This effect runs fresh each time
	$effect(() => {
		console.log(`Widget ${widgetId} effect running, count: ${clickCount}`)

		return () => {
			console.log(`Widget ${widgetId} effect cleanup`)
		}
	})

	onMount(() => {
		console.log(`Widget ${widgetId} mounted at ${new Date().toISOString()}`)
		lastInteraction = 'mounted'

		// Imagine this sets up WebSocket connections,
		// initializes third-party libraries, etc.
	})

	onDestroy(() => {
		console.log(`Widget ${widgetId} destroying...`)
		// Clean up WebSocket, third-party libraries, etc.
	})

	function handleClick() {
		clickCount++
		lastInteraction = `clicked at ${new Date().toLocaleTimeString()}`
	}
</script>

<div class="widget">
	<h3>Widget: {widgetId}</h3>
	<p>Clicks: {clickCount} (computed: {computedValue})</p>
	<p>Last interaction: {lastInteraction ?? 'none'}</p>
	<button onclick={handleClick}>Click me</button>
</div>

<!-- Parent.svelte -->
<script>
	let activeWidget = $state('alpha')
	let widgets = ['alpha', 'beta', 'gamma']
</script>

<select bind:value={activeWidget}>
	{#each widgets as w}
		<option value={w}>{w}</option>
	{/each}
</select>

<!-- With {#key}: Complete reset on change -->
{#key activeWidget}
	<StatefulWidget widgetId={activeWidget} />
{/key}

<!-- Without {#key}: Same instance, only props update
<StatefulWidget widgetId={activeWidget} />
-->

Quando Usar a Reinstanciação de Componentes

Use #key em torno de componentes quando:

O componente representa uma entidade conceitualmente diferente quando a chave muda (alternando entre perfis de usuário, diferentes registros de banco de dados, páginas distintas)
O estado interno do componente ficaria obsoleto ou enganoso se fosse mantido (estado de validação de formulário, estatísticas computadas, dados em cache)
O componente inicializa recursos custosos em onMount que dependem de props (conexões WebSocket com endpoints diferentes, contextos de canvas com configurações distintas)
A integração com bibliotecas de terceiros requer a destruição e recriação do DOM e do estado da biblioteca

Evite #key em torno de componentes quando:

O desempenho é crítico e o custo de recriação é perceptível
O componente tem uma inicialização custosa que não depende da chave
Você deseja preservar o progresso do usuário ou o estado interno durante mudanças de props
Atualizações simples de props atualizariam o componente corretamente

Padrão Avançado

Expressões de Chave Condicionais

A expressão de chave não precisa ser um valor simples—pode ser qualquer expressão, incluindo condicionais, objetos ou valores computados:

<script>
	let mode = $state('edit') // 'edit' | 'preview' | 'readonly'
	let documentId = $state('doc-123')
	let forceRefresh = $state(0)

	// Complex key: recreate when either condition changes
	let editorKey = $derived(`${documentId}-${mode === 'edit' ? 'editable' : 'static'}`)

	// Or: only recreate when document changes, not mode
	let documentKey = $derived(documentId)

	// Or: include manual refresh trigger
	let refreshableKey = $derived(`${documentId}-${forceRefresh}`)

	function hardRefresh() {
		forceRefresh++
	}
</script>

<!-- Strategy 1: Recreate on document OR edit mode change -->
{#key editorKey}
	<DocumentEditor {documentId} {mode} />
{/key}

<!-- Strategy 2: Only recreate on document change -->
{#key documentKey}
	<DocumentEditor {documentId} {mode} />
{/key}

<!-- Strategy 3: Include manual refresh capability -->
{#key refreshableKey}
	<DocumentEditor {documentId} {mode} />
{/key}

<button onclick={hardRefresh}>Force Refresh Editor</button>

Chaves Compostas com Objetos

Para cenários complexos, você pode querer usar chave com múltiplos valores. Embora você pudesse concatenar strings, uma abordagem mais limpa usa o rastreamento de dependências do Svelte:

<script>
	let filters = $state({
		category: 'all',
		sortBy: 'date',
		searchQuery: ''
	})

	let dataSource = $state('primary')

	// Key only on values that should trigger recreation
	let listKey = $derived({
		source: dataSource,
		category: filters.category
		// Deliberately excluding sortBy and searchQuery
		// because those can be handled with reactive updates
	})

	// For object keys, we need to serialize to a string
	// because object identity would change on every render
	let serializedKey = $derived(JSON.stringify(listKey))
</script>

{#key serializedKey}
	<FilteredList source={dataSource} {filters} />
{/key}

Ressalva importante: Ao usar objetos como chaves, lembre-se de que o JavaScript compara objetos por referência, não por valor. Dois objetos com conteúdo idêntico ainda são considerados diferentes. Sempre serialize para uma string ou use valores primitivos para um comportamento consistente.

Integração com Runes do Svelte 5

O bloco #key interage perfeitamente com o sistema de runes do Svelte 5, mas entender essas interações é fundamental para um uso eficaz.

`$state` e `#key`

Todas as declarações $state dentro de um bloco #key são redefinidas quando a chave muda:

<script>
	let sessionId = $state('session-1')

	function newSession() {
		sessionId = `session-${Date.now()}`
	}
</script>

{#key sessionId}
	{@const initialTime = Date.now()}

	<SessionTracker {sessionId}>
		<!-- This component's state is fully isolated per session -->
	</SessionTracker>
{/key}

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

	// These reset completely when parent key changes
	let events = $state([])
	let isActive = $state(true)
	let duration = $state(0)

	$effect(() => {
		if (!isActive) return

		const interval = setInterval(() => {
			duration++
		}, 1000)

		return () => clearInterval(interval)
	})

	function logEvent(type, data) {
		events = [...events, { type, data, timestamp: Date.now() }]
	}
</script>

<div class="session">
	<header>
		<span>Session: {sessionId}</span>
		<span>Duration: {duration}s</span>
		<span>Events: {events.length}</span>
	</header>

	{@render children?.()}

	<button onclick={() => logEvent('user_action', { button: 'test' })}> Log Event </button>
</div>

Ciclo de Vida de `$effect` em Blocos Key

Effects dentro de blocos #key seguem o padrão padrão de criação/destruição:

<script>
	let resourceId = $state('resource-a')

	// This effect is OUTSIDE the key block
	// It won't be destroyed/recreated, just re-runs when resourceId changes
	$effect(() => {
		console.log('Outer effect: resourceId is now', resourceId)
	})
</script>

{#key resourceId}
	<ResourceViewer {resourceId} />
{/key}

<!-- ResourceViewer.svelte -->
<script>
	import { onMount, onDestroy } from 'svelte'

	let { resourceId } = $props()

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

	// This effect runs on mount and never re-runs
	// (because resourceId comes from props and component is recreated)
	$effect(() => {
		console.log(`Effect setup for resource: ${resourceId}`)

		// Fetch data for this specific resource
		fetchResource(resourceId)
			.then((result) => {
				data = result
				loading = false
			})
			.catch((err) => {
				error = err
				loading = false
			})

		return () => {
			console.log(`Effect cleanup for resource: ${resourceId}`)
			// Cancel pending requests, close connections, etc.
		}
	})

	async function fetchResource(id) {
		const response = await fetch(`/api/resources/${id}`)
		if (!response.ok) throw new Error('Failed to fetch')
		return response.json()
	}
</script>

{#if loading}
	<div class="loading">Loading {resourceId}...</div>
{:else if error}
	<div class="error">Error: {error.message}</div>
{:else}
	<div class="resource-data">
		<h2>{data.title}</h2>
		<pre>{JSON.stringify(data, null, 2)}</pre>
	</div>
{/if}

Usando `$derived` com Blocos Key

Valores derivados fornecem uma maneira elegante de criar chaves compostas ou transformar valores de chave:

<script>
	let rawFilters = $state({
		page: 1,
		limit: 20,
		category: 'all',
		search: ''
	})

	// Derived key that only triggers recreation for significant changes
	let paginationKey = $derived({
		page: rawFilters.page,
		limit: rawFilters.limit,
		category: rawFilters.category
		// search is excluded - handled reactively within component
	})

	// Serialize for stable comparison
	let stableKey = $derived(JSON.stringify(paginationKey))

	// Could also use a hash function for shorter keys
	let hashedKey = $derived(simpleHash(stableKey))

	function simpleHash(str) {
		let hash = 0
		for (let i = 0; i < str.length; i++) {
			const char = str.charCodeAt(i)
			hash = (hash << 5) - hash + char
			hash = hash & hash // Convert to 32-bit integer
		}
		return hash.toString(36)
	}
</script>

{#key stableKey}
	<PaginatedResults filters={rawFilters} onPageChange={(page) => (rawFilters.page = page)} />
{/key}

Padrão do Mundo Real

Reset de Formulário ao Mudar de Contexto

Uma aplicação comum é redefinir formulários quando o contexto de edição muda:

<script>
	import UserEditForm from '$lib/components/UserEditForm.svelte'

	let users = $state([
		{ id: 1, name: 'Alice', email: 'alice@example.com', role: 'admin' },
		{ id: 2, name: 'Bob', email: 'bob@example.com', role: 'user' },
		{ id: 3, name: 'Charlie', email: 'charlie@example.com', role: 'user' }
	])

	let selectedUserId = $state(null)
	let selectedUser = $derived(users.find((u) => u.id === selectedUserId) ?? null)

	function handleSave(updatedData) {
		users = users.map((u) => (u.id === selectedUserId ? { ...u, ...updatedData } : u))
	}
</script>

<div class="user-management">
	<aside class="user-list">
		<h2>Users</h2>
		<ul>
			{#each users as user (user.id)}
				<li>
					<button
						onclick={() => (selectedUserId = user.id)}
						class:selected={selectedUserId === user.id}
					>
						{user.name}
					</button>
				</li>
			{/each}
		</ul>
	</aside>

	<main class="editor-panel">
		{#if selectedUser}
			{#key selectedUserId}
				<UserEditForm user={selectedUser} onSave={handleSave} />
			{/key}
		{:else}
			<p class="placeholder">Select a user to edit</p>
		{/if}
	</main>
</div>

<!-- /components/UserEditForm.svelte -->
<script>
	let { user, onSave } = $props()

	// Form state - completely fresh for each user
	let formData = $state({
		name: user.name,
		email: user.email,
		role: user.role
	})

	let touched = $state({
		name: false,
		email: false,
		role: false
	})

	let errors = $derived({
		name: touched.name && !formData.name.trim() ? 'Name is required' : null,
		email: touched.email && !isValidEmail(formData.email) ? 'Invalid email' : null,
		role: null
	})

	let isValid = $derived(
		Object.values(errors).every((e) => e === null) && Object.values(touched).some((t) => t)
	)

	let isDirty = $derived(
		formData.name !== user.name || formData.email !== user.email || formData.role !== user.role
	)

	function isValidEmail(email) {
		return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
	}

	function handleSubmit(e) {
		e.preventDefault()
		if (isValid && isDirty) {
			onSave(formData)
		}
	}

	function markTouched(field) {
		touched[field] = true
	}
</script>

<form onsubmit={handleSubmit}>
	<h3>Editing: {user.name}</h3>

	<div class="field" class:error={errors.name}>
		<label for="name">Name</label>
		<input id="name" type="text" bind:value={formData.name} onblur={() => markTouched('name')} />
		{#if errors.name}
			<span class="error-message">{errors.name}</span>
		{/if}
	</div>

	<div class="field" class:error={errors.email}>
		<label for="email">Email</label>
		<input
			id="email"
			type="email"
			bind:value={formData.email}
			onblur={() => markTouched('email')}
		/>
		{#if errors.email}
			<span class="error-message">{errors.email}</span>
		{/if}
	</div>

	<div class="field">
		<label for="role">Role</label>
		<select id="role" bind:value={formData.role} onchange={() => markTouched('role')}>
			<option value="user">User</option>
			<option value="admin">Admin</option>
		</select>
	</div>

	<footer class="form-actions">
		<span class="status">
			{#if isDirty}
				<span class="dirty-indicator">Unsaved changes</span>
			{/if}
		</span>
		<button type="submit" disabled={!isValid || !isDirty}> Save Changes </button>
	</footer>
</form>

<style>
	.field {
		margin-bottom: 1rem;
	}

	.field.error input,
	.field.error select {
		border-color: #ef4444;
	}

	.error-message {
		color: #ef4444;
		font-size: 0.875rem;
		margin-top: 0.25rem;
		display: block;
	}

	.dirty-indicator {
		color: #f59e0b;
		font-size: 0.875rem;
	}

	.form-actions {
		display: flex;
		justify-content: space-between;
		align-items: center;
		margin-top: 1.5rem;
	}
</style>

Sem #key, alternar entre usuários preservaria o estado do formulário de maneira inadequada — erros de validação de Alice apareceriam ao editar Bob, estados de interação seriam carregados junto, e a verificação de alterações estaria incorreta.

Padrão Avançado

Integração com Bibliotecas de Terceiros

Muitas bibliotecas de terceiros (bibliotecas de gráficos, editores de texto rico, componentes de mapa) não foram projetadas para atualizações reativas. Elas esperam ser inicializadas uma única vez com configuração e dados.

<script>
	import { onMount, onDestroy } from 'svelte'

	let { chartType, data, options } = $props()

	let container
	let chartInstance = null

	onMount(() => {
		// Initialize the third-party library
		// This only happens once per component instance
		chartInstance = new ThirdPartyChart(container, {
			type: chartType,
			data: data,
			...options
		})

		console.log('Chart initialized:', chartType)
	})

	onDestroy(() => {
		// Proper cleanup is essential
		if (chartInstance) {
			chartInstance.destroy()
			chartInstance = null
			console.log('Chart destroyed')
		}
	})
</script>

<div bind:this={container} class="chart-container"></div>

<!-- Parent using the chart -->
<script>
	let chartType = $state('bar')
	let dataset = $state('sales')

	let dataSets = {
		sales: [
			/* sales data */
		],
		revenue: [
			/* revenue data */
		],
		users: [
			/* user data */
		]
	}

	// Composite key: recreate when type OR data source changes
	let chartKey = $derived(`${chartType}-${dataset}`)
</script>

<select bind:value={chartType}>
	<option value="bar">Bar Chart</option>
	<option value="line">Line Chart</option>
	<option value="pie">Pie Chart</option>
</select>

<select bind:value={dataset}>
	<option value="sales">Sales Data</option>
	<option value="revenue">Revenue Data</option>
	<option value="users">User Data</option>
</select>

{#key chartKey}
	<ChartWrapper {chartType} data={dataSets[dataset]} options={{ responsive: true }} />
{/key}

Esse padrão garante que a biblioteca de gráficos seja devidamente destruída e reinicializada sempre que a configuração mudar de forma significativa.

Considerações de Desempenho e Otimização

Embora o #key seja poderoso, ele traz implicações de desempenho que devem ser cuidadosamente consideradas.

O Custo da Recriação

Toda mudança de #key dispara:

Destruição do DOM: Elementos são removidos, ouvintes de eventos são desanexados
Destruição do componente: Callbacks de onDestroy são executados, effects fazem limpeza
Desalocação de memória: Referências anteriores de estado e DOM tornam-se lixo
Criação do DOM: Novos elementos são criados a partir do template
Inicialização do componente: Código do construtor é executado, $state é inicializado
Configuração de effects: Blocos $effect executam sua inicialização
Callbacks de montagem: Funções onMount são executadas
Execução de transições: Se houver transições presentes, elas são animadas

Para elementos simples, esse custo é negligenciável. Para árvores de componentes complexas com muitos effects, busca de dados e integrações com terceiros, o custo pode ser substancial.

Medindo o Impacto

<script>
	let key = $state(0)
	let recreationTimes = $state([])

	function measureRecreation() {
		const start = performance.now()
		key++
		// Use requestAnimationFrame to measure after DOM updates
		requestAnimationFrame(() => {
			const duration = performance.now() - start
			recreationTimes = [...recreationTimes.slice(-9), duration]
		})
	}

	let averageTime = $derived(
		recreationTimes.length > 0
			? (recreationTimes.reduce((a, b) => a + b, 0) / recreationTimes.length).toFixed(2)
			: 0
	)
</script>

{#key key}
	<ExpensiveComponent />
{/key}

<button onclick={measureRecreation}> Trigger Recreation </button>

<p>Average recreation time: {averageTime}ms</p>
<p>Last 10 times: {recreationTimes.map((t) => t.toFixed(1)).join(', ')}ms</p>

Estratégias de Otimização

1. Restrinja o Escopo

Envolva com #key apenas o conteúdo estritamente necessário:

<!-- Less optimal: recreates the entire panel -->
{#key userId}
	<div class="user-panel">
		<Header title="User Profile" />
		<Navigation items={navItems} />
		<UserDetails {userId} />
		<ActivityFeed {userId} />
	</div>
{/key}

<!-- More optimal: only recreate what needs recreation -->
<div class="user-panel">
	<Header title="User Profile" />
	<Navigation items={navItems} />
	{#key userId}
		<UserDetails {userId} />
		<ActivityFeed {userId} />
	{/key}
</div>

2. Debounce em Mudanças Rápidas

Se a chave puder mudar rapidamente (por exemplo, durante a digitação), aplique debounce ao valor:

<script>
	let searchInput = $state('')
	let debouncedSearch = $state('')
	let debounceTimer

	$effect(() => {
		clearTimeout(debounceTimer)
		debounceTimer = setTimeout(() => {
			debouncedSearch = searchInput
		}, 300)

		return () => clearTimeout(debounceTimer)
	})
</script>

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

<!-- Don't key on searchInput directly - too many recreations -->
{#key debouncedSearch}
	<SearchResults query={debouncedSearch} />
{/key}

3. Considere Alternativas

Antes de usar #key, avalie se o problema pode ser resolvido de outra forma:

<script>
	// Alternative 1: Manual reset function instead of key block
	let formRef

	function resetForm() {
		formRef?.reset()
	}

	// Alternative 2: Reactive prop that triggers internal reset
	// (component can watch for changes and reset itself)
</script>

<!-- Using key -->
{#key userId}
	<UserForm {userId} />
{/key}

<!-- Alternative: External reset trigger -->
<UserForm {userId} bind:this={formRef} />
<button onclick={resetForm}>Reset Form</button>

Armadilhas Comuns e Como Evitá-las

1. Expressões de Chave Instáveis

<script>
	let data = $state({ id: 1, name: 'Test' })
</script>

<!-- WRONG: Object identity changes every render -->
{#key { id: data.id }}
	<Component />
{/key}

<!-- CORRECT: Use a primitive value -->
{#key data.id}
	<Component />
{/key}

<!-- CORRECT: If you need multiple values, serialize them -->
{#key `${data.id}-${data.category}`}
	<Component />
{/key}

2. Chaves que Mudam com Muita Frequência

<script>
	let searchResults = $state([])
	let lastSearchTime = $state(Date.now())

	async function search(query) {
		const results = await fetchResults(query)
		searchResults = results
		lastSearchTime = Date.now() // Changes on every search!
	}
</script>

<!-- WRONG: lastSearchTime changes with results, causing double recreation -->
{#key `${searchResults.length}-${lastSearchTime}`}
	<ResultsList items={searchResults} />
{/key}

<!-- CORRECT: Only key on meaningful changes -->
{#key searchResults.length > 0 ? searchResults[0]?.id : 'empty'}
	<ResultsList items={searchResults} />
{/key}

3. Esquecer a Conclusão das Transições

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

	let items = $state(['a', 'b', 'c'])
	let selectedIndex = $state(0)

	// Rapid clicks can cause visual glitches
	function quickNav() {
		selectedIndex = (selectedIndex + 1) % items.length
	}
</script>

<!-- Transitions may overlap in unexpected ways with rapid key changes -->
{#key items[selectedIndex]}
	<div transition:fade={{ duration: 500 }}>
		{items[selectedIndex]}
	</div>
{/key}

<button onclick={quickNav}>Quick Navigate</button>

Para lidar com isso de forma elegante, encurte as transições para interações rápidas ou implemente um rastreamento adequado do estado de transição conforme mostrado anteriormente.

4. Usar Índices em Vez de Identidade como Chave

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

	let selectedIndex = $state(0)

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

<!-- WRONG: Keying on index - removing item 0 causes item 1 to take index 0 
     but it won't be recreated since the key (0) hasn't changed -->
{#key selectedIndex}
	<TodoEditor todo={todos[selectedIndex]} />
{/key}

<!-- CORRECT: Key on the item's actual identity -->
{#key todos[selectedIndex]?.id}
	<TodoEditor todo={todos[selectedIndex]} />
{/key}

5. Perder Estado Importante Sem Querer

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

<!-- This destroys scroll position when view mode changes! -->
{#key viewMode}
	<ItemView mode={viewMode} bind:scrollTop={scrollPosition} />
{/key}

<!-- Solution 1: Don't use key if the component can handle the change -->
<ItemView mode={viewMode} scrollTop={scrollPosition} />

<!-- Solution 2: Preserve and restore state explicitly -->
{#key viewMode}
	<ItemView
		mode={viewMode}
		initialScroll={scrollPosition}
		onScroll={(pos) => (scrollPosition = pos)}
	/>
{/key}

Resumo e Boas Práticas

O bloco #key é uma ferramenta de precisão para controlar o ciclo de vida do DOM e dos componentes no Svelte 5. Aqui estão os principais pontos:

Quando Usar `#key`

Disparar transições em mudanças de valor, não apenas em mudanças de presença
Redefinir o estado do componente quando a entidade conceitual muda
Integrar bibliotecas de terceiros que não suportam atualizações reativas
Forçar a reinicialização de effects que devem ser executados do zero
Limpar o estado de formulários ao alternar entre registros diferentes

Quando NÃO Usar `#key`

Atualizações simples de props que os componentes tratam corretamente
Mudanças de alta frequência sem debouncing adequado
Árvores de componentes grandes onde o custo de recriação é proibitivo
Preservar posição de scroll, foco ou seleção entre atualizações

Lista de Boas Práticas

Use valores primitivos ou strings devidamente serializadas como chaves
Mantenha o escopo do #key o mais restrito possível
Considere aplicar debouncing em chaves que mudam rapidamente
Trate eventos de transição se precisar coordenar animações complexas
Teste se a limpeza em onDestroy e os teardowns de efeitos funcionam corretamente
Meça o impacto no desempenho em componentes complexos
Documente por que o #key é necessário em casos não óbvios

Conclusão

O bloco #key representa uma das soluções mais elegantes do Svelte para um desafio comum no frontend: forçar a recriação seletiva de componentes quando mudanças de identidade importam mais do que atualizações individuais de props. Ao compreender profundamente sua mecânica — como ele destrói e recria subárvores do DOM, quando as transições são disparadas e como as funções de limpeza são executadas — você pode utilizar essa ferramenta de forma eficaz para construir aplicações mais previsíveis, manuteníveis e performáticas.

O poder do #key está em sua precisão. Ao contrário de soluções grosseiras, como remontar árvores inteiras de componentes, os blocos #key permitem que você identifique exatamente quais componentes devem ser reiniciados quando valores específicos mudam. Combinado com debouncing adequado para mudanças de alta frequência, minimização cuidadosa do escopo e testes de comportamentos de limpeza, os blocos #key se transformam de um simples recurso de sintaxe em uma ferramenta arquitetural para gerenciar o ciclo de vida dos componentes com precisão cirúrgica.

Pontos Principais

Blocos #key forçam a recriação de seu conteúdo quando a expressão da chave muda, destruindo a subárvore antiga e criando uma instância nova com estado limpo
Transições são disparadas em mudanças de chave mesmo quando o conteúdo permanece no DOM, permitindo animações acionadas por mudanças de valor em vez de apenas presença/ausência
O estado do componente é completamente reiniciado, incluindo todos os $state, variáveis locais, assinaturas de $effect e hooks de ciclo de vida onMount/onDestroy
Expressões de chave devem retornar valores primitivos ou referências de objeto estáveis — objetos/arrays devem ser serializados com JSON.stringify() para uma verificação de identidade confiável
Funções de limpeza sempre são executadas antes da recriação, garantindo o descarte adequado de recursos, remoção de event listeners e teardown de integrações com bibliotecas de terceiros
O custo de desempenho é proporcional ao tamanho da subárvore — envolva apenas o conteúdo mínimo necessário, não árvores inteiras de componentes, para minimizar o overhead de recriação
O debouncing previne recriações rápidas quando as chaves mudam frequentemente (por exemplo, a partir de inputs de texto), usando técnicas como debounce com setTimeout ou $derived com throttling
Os casos de uso mais comuns incluem a reinicialização de formulários, o disparo de animações de entrada em mudanças de valor e a reinicialização de bibliotecas de terceiros que não possuem APIs reativas

Veja Também

Documentação Oficial do Svelte 5 - {#key}
Transições do Svelte - Animando mudanças em blocos key
Animações do Svelte - A diretiva animate:flip para reordenação de listas
onMount e onDestroy - Hooks de ciclo de vida que são reiniciados com mudanças de chave
$effect - Efeitos colaterais que são reexecutados na recriação do bloco key

Controle do Ciclo de Vida de Componentes e Recriação Estratégica do DOM

Entendendo o Problema Fundamental: Atualizações vs. Recriação

A Anatomia do {#key ...}

Sintaxe e Semântica

Uma Demonstração Simples

Análise Aprofundada

#key com Transições

O Problema de Temporização das Transições

A Solução com #key

Orquestração Avançada de Transições

Eventos de Transição com #key

Reinstanciação de Componentes

A Opção Nuclear

Entendendo o que é Redefinido

Quando Usar a Reinstanciação de Componentes

Padrão Avançado

Expressões de Chave Condicionais

Chaves Compostas com Objetos

Integração com Runes do Svelte 5

$state e #key

Ciclo de Vida de $effect em Blocos Key

Usando $derived com Blocos Key

Padrão do Mundo Real

Reset de Formulário ao Mudar de Contexto

Padrão Avançado

Integração com Bibliotecas de Terceiros

Considerações de Desempenho e Otimização

O Custo da Recriação

Medindo o Impacto

Estratégias de Otimização

Armadilhas Comuns e Como Evitá-las

1. Expressões de Chave Instáveis

2. Chaves que Mudam com Muita Frequência

3. Esquecer a Conclusão das Transições

4. Usar Índices em Vez de Identidade como Chave

5. Perder Estado Importante Sem Querer

Resumo e Boas Práticas

Quando Usar #key

Quando NÃO Usar #key

Lista de Boas Práticas

Conclusão

Pontos Principais

Veja Também

A Anatomia do `{#key ...}`

`#key` com Transições

A Solução com `#key`

Eventos de Transição com `#key`

`$state` e `#key`

Ciclo de Vida de `$effect` em Blocos Key

Usando `$derived` com Blocos Key

Quando Usar `#key`

Quando NÃO Usar `#key`