Control del Ciclo de Vida de Componentes y Recreación Estratégica del DOM

En el panorama de los frameworks reactivos modernos, uno de los desafíos más sutiles que enfrentan los desarrolladores es controlar con precisión cuándo y cómo los elementos del DOM y los componentes deben recrearse en lugar de simplemente actualizarse. El bloque {#key ...} de Svelte 5 ofrece una solución elegante a este problema: un mecanismo declarativo que instruye al compilador a destruir y recrear su contenido cada vez que una expresión especificada cambia de valor.

Aunque el concepto parece deceptivamente simple en la superficie, dominar el bloque {#key ...} requiere una comprensión profunda del modelo de reactividad de Svelte, la mecánica del ciclo de vida de los componentes y la sutil interacción entre las actualizaciones del DOM y la ejecución de JavaScript. Este tutorial te guiará a través del espectro completo de uso de {#key ...}, desde los conceptos fundamentales hasta los patrones arquitectónicos avanzados que pueden transformar tu enfoque del diseño de componentes.

Comprendiendo el Problema Fundamental: Actualizaciones vs. Recreación

Antes de adentrarse en la sintaxis y la mecánica de {#key ...}, es esencial entender el problema que resuelve. El sistema de reactividad de Svelte es notablemente eficiente: cuando el estado cambia, Svelte actualiza quirúrgicamente solo las partes del DOM que dependen de ese estado. Este enfoque granular minimiza la manipulación del DOM y ofrece un excelente rendimiento.

Sin embargo, esta eficiencia crea un desafío: a veces no quieres actualizaciones granulares. A veces necesitas destruir y recrear completamente una parte del DOM o una instancia de componente. Considera estos escenarios:

Escenario 1: Restablecimiento del Estado Interno de un Componente Imagina un componente de formulario que mantiene su propio estado interno de validación, seguimiento de campos tocados y mensajes de error. Cuando el usuario cambia de editar al "Usuario A" al "Usuario B," quieres un formulario completamente nuevo, no uno que arrastre los errores de validación del usuario anterior.

Escenario 2: Activar Animaciones en Cambios de Datos Tienes un componente de notificación con una animación de entrada. Cuando llega una nueva notificación, quieres que la animación se reproduzca nuevamente. Pero como Svelte actualiza eficientemente el contenido de texto del nodo DOM existente, la animación nunca se vuelve a activar.

Escenario 3: Integración de Bibliotecas de Terceros Estás integrando una biblioteca de gráficos que se inicializa una vez en onMount y no admite actualizaciones reactivas. Cuando cambia tu fuente de datos, necesitas destruir la instancia anterior del gráfico y crear una nueva.

El bloque {#key ...} resuelve elegantemente todos estos escenarios al proporcionar control explícito sobre el ciclo de vida de destrucción/creación.

La Anatomía de `{#key ...}`

Sintaxis y Semántica

La sintaxis básica del bloque {#key ...} es sencilla:

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

La expression puede ser cualquier expresión de JavaScript que Svelte pueda rastrear reactivamente. Cuando el valor de esta expresión cambia (usando la comparación de igualdad estricta de JavaScript), Svelte realiza la siguiente secuencia:

Fase de Destrucción: Todos los elementos del DOM dentro del bloque son eliminados. Los componentes son destruidos, activando sus callbacks onDestroy. Las transiciones en ejecución completan su fase de salida.
Fase de Creación: Se crean nuevos elementos del DOM desde cero. Los componentes se instancian de nuevo, activando su código de inicialización y los callbacks onMount. Las transiciones de entrada comienzan a reproducirse.

Este ciclo de destrucción y luego creación es fundamentalmente diferente del comportamiento normal de actualización de Svelte, donde los nodos del DOM existentes se modifican en su lugar.

Una Demostración Simple

Comencemos con un ejemplo fundamental que ilustra el comportamiento básico:

<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 haces clic en el botón, observa que:

El componentId cambia (lo que demuestra que se creó una nueva instancia)
El callback onDestroy se dispara antes del nuevo onMount
El internalState se restablece completamente: el nuevo componente no tiene conocimiento del estado de la instancia anterior

Este comportamiento es determinista y predecible, lo cual es crucial para construir aplicaciones confiables.

Análisis en Profundidad

`#key` con Transiciones

Una de las aplicaciones más poderosas de #key es controlar la reproducción de transiciones. El sistema de transiciones de Svelte está íntimamente conectado con la creación y destrucción de elementos: las transiciones se reproducen cuando los elementos entran o salen del DOM. El bloque #key te da control preciso sobre cuándo ocurren estos eventos del ciclo de vida.

El Problema del Tiempo en las Transiciones

Considera este escenario común sin #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>

En este código, la transición nunca se reproduce después del renderizado inicial. ¿Por qué? Porque Svelte actualiza eficientemente el contenido de texto del elemento <p> existente en lugar de destruirlo y recrearlo. El elemento nunca sale ni entra al DOM, por lo que no se activa ninguna transición.

La Solución con `#key`

Envolver el elemento en un bloque #key resuelve esto elegantemente:

<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>

Ahora cada cambio de mensaje activa una recreación completa del elemento <p>, y la transición se reproduce cada vez. El elemento antiguo sale volando mientras el nuevo elemento entra volando.

Orquestación Avanzada de Transiciones

Para efectos más sofisticados, puedes combinar #key con directivas separadas in: y 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>

Este patrón crea una presentación de diapositivas estilo carrusel donde la dirección de la transición se adapta según la dirección de navegación. El {#key currentSlide} asegura que incluso la navegación rápida active correctamente la secuencia de animación.

Eventos de Transición con `#key`

Las transiciones de Svelte emiten eventos que puedes capturar para coordinar animaciones complejas o activar efectos secundarios:

<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>

Este patrón es invaluable cuando necesitas deshabilitar las interacciones del usuario durante las transiciones, mostrar estados de carga o coordinar múltiples elementos animados.

Reinstanciación de Componentes

La Opción Nuclear

Cuando #key envuelve un componente, el ciclo de vida completo del componente se restablece. Esto es tanto poderoso como potencialmente peligroso: es la "opción nuclear" para la gestión de estado.

Entendiendo Qué Se Restablece

Cuando un componente dentro de #key es recreado:

Todo el $state interno se restablece a los valores iniciales
Todos los valores $derived se recalculan desde cero
Todos los bloques $effect ejecutan su configuración nuevamente
Los callbacks onMount se disparan como si el componente acabara de agregarse a la página
Cualquier limpieza onDestroy de la instancia anterior se ejecuta primero
Los valores enlazados se re-sincronizan con los nuevos elementos del DOM
El contexto se re-hereda de los componentes padre (aunque los valores del contexto en sí pueden ser las mismas referencias)

<!-- 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} />
-->

Cuándo Usar la Reinstanciación de Componentes

Usa #key alrededor de componentes cuando:

El componente representa una entidad conceptualmente diferente cuando la clave cambia (cambio entre perfiles de usuario, diferentes registros de base de datos, páginas distintas)
El estado interno del componente se volvería obsoleto o engañoso si se mantuviera (estado de validación de formularios, estadísticas calculadas, datos en caché)
El componente inicializa recursos costosos en onMount que dependen de las props (conexiones WebSocket a diferentes endpoints, contextos de canvas con diferentes configuraciones)
La integración de bibliotecas de terceros requiere destruir y recrear el DOM y el estado de la biblioteca

Evita #key alrededor de componentes cuando:

El rendimiento es crítico y el costo de recreación es notable
El componente tiene una inicialización costosa que no depende de la clave
Quieres preservar el progreso del usuario o el estado interno durante los cambios de props
Las actualizaciones simples de props actualizarían correctamente el componente

Patrón Avanzado

Expresiones de Clave Condicionales

La expresión de clave no tiene que ser un valor simple: puede ser cualquier expresión, incluyendo condicionales, objetos o valores calculados:

<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>

Claves Compuestas con Objetos

Para escenarios complejos, es posible que quieras usar una clave basada en múltiples valores. Aunque podrías concatenar cadenas de texto, un enfoque más limpio utiliza el seguimiento de dependencias de 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}

Advertencia importante: Al usar objetos como claves, recuerda que JavaScript compara los objetos por referencia, no por valor. Dos objetos con contenidos idénticos siguen considerándose diferentes. Siempre serializa a una cadena de texto o usa valores primitivos para un comportamiento consistente.

Integración con las Runas de Svelte 5

El bloque #key interactúa sin problemas con el sistema de runas de Svelte 5, pero entender estas interacciones es crucial para un uso efectivo.

`$state` y `#key`

Todas las declaraciones $state dentro de un bloque #key se reinician cuando la clave cambia:

<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` en Bloques Key

Los efectos dentro de los bloques #key siguen el patrón estándar de creación/destrucción:

<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}

Usar `$derived` con Bloques Key

Los valores derivados proporcionan una forma elegante de crear claves compuestas o transformar valores de clave:

<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}

Patrones del Mundo Real

Reinicio de Formulario al Cambiar el Contexto

Una aplicación común es reiniciar formularios cuando cambia el contexto de edición:

<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>

Sin #key, cambiar entre usuarios preservaría el estado del formulario de manera inapropiada: los errores de validación de Alice se mostrarían al editar a Bob, los estados de "tocado" se transferirían, y la verificación de cambios sería incorrecta.

Patrones Avanzados

Integración con Bibliotecas de Terceros

Muchas bibliotecas de terceros (bibliotecas de gráficos, editores de texto enriquecido, componentes de mapas) no están diseñadas para actualizaciones reactivas. Esperan ser inicializadas una vez con configuración y datos.

<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}

Este patrón garantiza que la biblioteca de gráficos sea correctamente destruida y reinicializada cada vez que la configuración cambie significativamente.

Consideraciones de Rendimiento y Optimización

Aunque #key es poderoso, conlleva implicaciones de rendimiento que debes considerar cuidadosamente.

El Costo de la Recreación

Cada cambio de #key desencadena:

Destrucción del DOM: Los elementos son eliminados, los escuchadores de eventos desconectados
Destrucción del componente: Los callbacks de onDestroy se ejecutan, los efectos se limpian
Liberación de memoria: El estado anterior y las referencias al DOM se convierten en basura
Creación del DOM: Se crean nuevos elementos a partir de la plantilla
Inicialización del componente: El código del constructor se ejecuta, $state se inicializa
Configuración de efectos: Los bloques $effect ejecutan su inicialización
Callbacks de montaje: Las funciones onMount se ejecutan
Ejecución de transiciones: Si hay transiciones presentes, se animan

Para elementos simples, este costo es insignificante. Para árboles de componentes complejos con muchos efectos, obtención de datos e integraciones de terceros, el costo puede ser considerable.

Midiendo el 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>

Estrategias de Optimización

1. Reducir el Alcance

Envuelve en #key solo el contenido mínimo necesario:

<!-- 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. Desacelerar Cambios Rápidos con Debounce

Si la clave puede cambiar rápidamente (por ejemplo, durante la escritura), aplica debounce al 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. Considerar Alternativas

Antes de usar #key, considera si el problema puede resolverse de otra manera:

<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>

Errores Comunes y Cómo Evitarlos

1. Expresiones de Clave Inestables

<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. Claves que Cambian con Demasiada Frecuencia

<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. Olvidar la Finalización de las Transiciones

<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 manejar esto con elegancia, ya sea acorta las transiciones para interacciones rápidas o implementa un seguimiento adecuado del estado de las transiciones como se mostró anteriormente.

4. Usar Índices en Lugar de Identidad como Clave

<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 sin Intención

<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}

Resumen y Buenas Prácticas

El bloque #key es una herramienta de precisión para controlar el ciclo de vida del DOM y los componentes en Svelte 5. Aquí están los puntos clave a recordar:

Cuándo Usar `#key`

Disparar transiciones ante cambios de valor, no solo cambios de presencia
Reiniciar el estado del componente cuando la entidad conceptual cambia
Integrar bibliotecas de terceros que no soportan actualizaciones reactivas
Forzar la reinicialización de efectos que deben ejecutarse de nuevo
Limpiar el estado de formularios al cambiar entre diferentes registros

Cuándo NO Usar `#key`

Actualizaciones simples de props que los componentes manejan correctamente
Cambios de alta frecuencia sin el debouncing adecuado
Árboles de componentes grandes donde el costo de recreación es prohibitivo
Preservar la posición de scroll, el foco o la selección entre actualizaciones

Lista de Buenas Prácticas

Usar valores primitivos o cadenas correctamente serializadas como claves
Mantener el alcance de #key lo más reducido posible
Considerar el debouncing para claves que cambian rápidamente
Manejar los eventos de transición si se necesita coordinar animaciones complejas
Verificar que la limpieza en onDestroy y los teardowns de efectos funcionen correctamente
Medir el impacto en el rendimiento en componentes complejos
Documentar por qué #key es necesario en los casos no obvios

Conclusión

El bloque #key representa una de las soluciones más elegantes de Svelte a un desafío común en el frontend: forzar la recreación selectiva de componentes cuando los cambios de identidad importan más que las actualizaciones individuales de props. Al comprender en profundidad su funcionamiento —cómo destruye y recrea subárboles del DOM, cuándo se disparan las transiciones y cómo se ejecutan las funciones de limpieza— podrás utilizar esta herramienta de manera efectiva para construir aplicaciones más predecibles, mantenibles y eficientes.

El poder de #key radica en su precisión. A diferencia de soluciones de grano grueso como el remontaje de árboles de componentes enteros, los bloques #key te permiten identificar exactamente qué componentes deben reiniciarse cuando cambian valores específicos. Combinados con el debouncing adecuado para cambios de alta frecuencia, una minimización reflexiva del alcance y pruebas de los comportamientos de limpieza, los bloques #key se transforman de una simple característica de sintaxis en una herramienta arquitectónica para gestionar el ciclo de vida de los componentes con precisión quirúrgica.

Puntos Clave

Los bloques #key fuerzan la recreación de su contenido cuando la expresión clave cambia, destruyendo el subárbol anterior y creando una instancia nueva con estado limpio
Las transiciones se disparan ante cambios de clave incluso cuando el contenido permanece en el DOM, habilitando animaciones activadas por cambios de valor en lugar de solo por presencia/ausencia
El estado del componente se reinicia por completo, incluyendo todos los $state, variables locales, suscripciones de $effect y hooks de ciclo de vida onMount/onDestroy
Las expresiones de clave deben devolver valores primitivos o referencias de objeto estables — los objetos/arrays deben serializarse con JSON.stringify() para una verificación de identidad confiable
Las funciones de limpieza siempre se ejecutan antes de la recreación, garantizando la liberación adecuada de recursos, la eliminación de event listeners y el teardown de integraciones con librerías de terceros
El costo de rendimiento es proporcional al tamaño del subárbol — envuelve solo el contenido mínimo necesario, no árboles de componentes enteros, para minimizar la sobrecarga de recreación
El debouncing previene la recreación rápida cuando las claves cambian con frecuencia (p. ej., desde inputs de texto) usando técnicas como debounce con setTimeout o $derived con throttling
Los casos de uso comunes incluyen reiniciar formularios, disparar animaciones de entrada ante cambios de valor y reinicializar librerías de terceros que carecen de APIs reactivas

Ver También

Documentación oficial de Svelte 5 - {#key}
Transiciones de Svelte - Animación de cambios en bloques key
Animaciones de Svelte - La directiva animate:flip para reordenamiento de listas
onMount y onDestroy - Hooks de ciclo de vida que se reinician con los cambios de clave
$effect - Efectos secundarios que se vuelven a ejecutar al recrear el bloque key