Component Lifecycle Control and Strategic DOM Recreation

In the landscape of modern reactive frameworks, one of the most nuanced challenges developers face is controlling precisely when and how DOM elements and components should be recreated rather than merely updated. Svelte 5’s {#key ...} block provides an elegant solution to this problem—a declarative mechanism that instructs the compiler to destroy and recreate its contents whenever a specified expression changes value.

While the concept appears deceptively simple on the surface, mastering the {#key ...} block requires a deep understanding of Svelte’s reactivity model, component lifecycle mechanics, and the subtle interplay between DOM updates and JavaScript execution. This tutorial will guide you through the complete spectrum of {#key ...} usage, from foundational concepts to advanced architectural patterns that can transform how you approach component design.

Understanding the Fundamental Problem: Updates vs. Recreation

Before diving into the syntax and mechanics of {#key ...}, it’s essential to understand the problem it solves. Svelte’s reactivity system is remarkably efficient—when state changes, Svelte surgically updates only the parts of the DOM that depend on that state. This granular approach minimizes DOM manipulation and delivers excellent performance.

However, this efficiency creates a challenge: sometimes you don’t want granular updates. Sometimes you need to completely destroy and recreate a piece of the DOM or a component instance. Consider these scenarios:

Scenario 1: Resetting Component Internal State Imagine a form component that maintains its own internal validation state, touched fields tracking, and error messages. When the user switches from editing “User A” to “User B,” you want a completely fresh form—not one that carries over validation errors from the previous user.

Scenario 2: Triggering Animations on Data Changes You have a notification component with an entrance animation. When a new notification arrives, you want the animation to play again. But since Svelte efficiently updates the existing DOM node’s text content, the animation never re-triggers.

Scenario 3: Third-Party Library Integration You’re integrating a charting library that initializes once in onMount and doesn’t support reactive updates. When your data source changes, you need to destroy the old chart instance and create a new one.

The {#key ...} block elegantly solves all these scenarios by providing explicit control over the destruction/creation lifecycle.

The Anatomy of {#key ...}

Syntax and Semantics

The basic syntax of the {#key ...} block is straightforward:

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

The expression can be any JavaScript expression that Svelte can track reactively. When this expression’s value changes (using JavaScript’s strict equality comparison), Svelte performs the following sequence:

  1. Destruction Phase: All DOM elements within the block are removed. Any components are destroyed, triggering their onDestroy callbacks. Any running transitions complete their outro phase.

  2. Creation Phase: New DOM elements are created from scratch. Components are freshly instantiated, triggering their initialization code and onMount callbacks. Intro transitions begin playing.

This destruction-then-creation cycle is fundamentally different from Svelte’s normal update behavior, where existing DOM nodes are modified in place.

A Simple Demonstration

Let’s begin with a foundational example that illustrates the core behavior:

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

Each time you click the button, observe that:

  1. The componentId changes (proving a new instance was created)
  2. The onDestroy callback fires before the new onMount
  3. The internalState resets completely—the new component has no knowledge of the previous instance’s state

This behavior is deterministic and predictable, which is crucial for building reliable applications.

Deep Dive

#key with Transitions

One of the most powerful applications of #key is controlling transition playback. Svelte’s transition system is intimately connected to element creation and destruction—transitions play when elements enter or leave the DOM. The #key block gives you precise control over when these lifecycle events occur.

The Transition Timing Problem

Consider this common scenario without #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>

In this code, the transition never plays after the initial render. Why? Because Svelte efficiently updates the text content of the existing <p> element rather than destroying and recreating it. The element never leaves or enters the DOM, so no transition is triggered.

The #key Solution

Wrapping the element in a #key block solves this elegantly:

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

Now each message change triggers a complete recreation of the <p> element, and the transition plays every time. The old element flies out while the new element flies in.

Advanced Transition Orchestration

For more sophisticated effects, you can combine #key with separate in: and out: directives:

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

This pattern creates a carousel-like slideshow where the transition direction adapts based on navigation direction. The {#key currentSlide} ensures that even rapid navigation properly triggers the animation sequence.

Transition Events with #key

Svelte transitions emit events that you can capture to coordinate complex animations or trigger side effects:

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

This pattern is invaluable when you need to disable user interactions during transitions, show loading states, or coordinate multiple animated elements.

Component Reinstantiation

The Nuclear Option

When #key wraps a component, the entire component lifecycle is reset. This is both powerful and potentially dangerous—it’s the “nuclear option” for state management.

Understanding What Gets Reset

When a component inside #key is recreated:

  1. All internal $state is reset to initial values
  2. All $derived values are recalculated from scratch
  3. All $effect blocks run their setup code again
  4. onMount callbacks fire as if the component was just added to the page
  5. Any onDestroy cleanup from the previous instance runs first
  6. Bound values are re-synchronized with new DOM elements
  7. Context is re-inherited from parent components (though the context values themselves may be the same references)
<!-- 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} />
-->

When to Use Component Reinstantiation

Use #key around components when:

  1. The component represents a conceptually different entity when the key changes (switching between user profiles, different database records, distinct pages)

  2. Internal component state would become stale or misleading if carried over (form validation state, computed statistics, cached data)

  3. The component initializes expensive resources in onMount that depend on props (WebSocket connections to different endpoints, canvas contexts with different configurations)

  4. Third-party library integration requires destroying and recreating the library’s DOM and state

Avoid #key around components when:

  1. Performance is critical and the recreation cost is noticeable
  2. The component has expensive initialization that doesn’t depend on the key
  3. You want to preserve user progress or internal state during prop changes
  4. Simple prop updates would correctly update the component

Advanced Pattern

Conditional Key Expressions

The key expression doesn’t have to be a simple value—it can be any expression, including conditionals, objects, or computed values:

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

Composite Keys with Objects

For complex scenarios, you might want to key on multiple values. While you could concatenate strings, a cleaner approach uses Svelte’s dependency tracking:

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

Important caveat: When using objects as keys, remember that JavaScript compares objects by reference, not by value. Two objects with identical contents are still considered different. Always serialize to a string or use primitive values for consistent behavior.

Integration with Svelte 5 Runes

The #key block interacts seamlessly with Svelte 5’s runes system, but understanding these interactions is crucial for effective usage.

$state and #key

All $state declarations inside a #key block are reset when the key changes:

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

$effect Lifecycle in Key Blocks

Effects inside #key blocks follow the standard creation/destruction pattern:

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

Using $derived with Key Blocks

Derived values provide an elegant way to create compound keys or transform key values:

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

Real-World Pattern

Form Reset on Context Change

A common application is resetting forms when the editing context changes:

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

Without #key, switching between users would preserve form state inappropriately—validation errors from Alice would show when editing Bob, touched states would carry over, and the dirty checking would be incorrect.

Advanced Pattern

Third-Party Library Integration

Many third-party libraries (charting libraries, rich text editors, map components) aren’t designed for reactive updates. They expect to be initialized once with configuration and data.

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

This pattern ensures the chart library is properly destroyed and reinitialized whenever the configuration changes significantly.

Performance Considerations and Optimization

While #key is powerful, it comes with performance implications that you must carefully consider.

The Cost of Recreation

Every #key change triggers:

  1. DOM destruction: Elements are removed, event listeners detached
  2. Component destruction: onDestroy callbacks fire, effects clean up
  3. Memory deallocation: Previous state and DOM references become garbage
  4. DOM creation: New elements are created from template
  5. Component initialization: Constructor code runs, $state initializes
  6. Effect setup: $effect blocks run their initialization
  7. Mount callbacks: onMount functions execute
  8. Transition execution: If transitions are present, they animate

For simple elements, this cost is negligible. For complex component trees with many effects, data fetching, and third-party integrations, the cost can be substantial.

Measuring Impact

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

Optimization Strategies

1. Narrow the Scope

Only wrap the minimum necessary content in #key:

<!-- 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 Rapid Changes

If the key might change rapidly (e.g., during typing), debounce the value:

<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. Consider Alternatives

Before using #key, consider whether the problem can be solved differently:

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

Common Pitfalls and How to Avoid Them

1. Unstable Key Expressions

<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. Keys That Change Too Often

<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. Forgetting About Transition Completion

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

To handle this gracefully, either shorten transitions for rapid interactions or implement proper transition state tracking as shown earlier.

4. Keying on Indices Instead of Identity

<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. Losing Important State Unintentionally

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

Summary and Best Practices

The #key block is a precision tool for controlling DOM and component lifecycle in Svelte 5. Here are the key takeaways:

When to Use #key

  • Triggering transitions on value changes, not just presence changes
  • Resetting component state when the conceptual entity changes
  • Integrating third-party libraries that don’t support reactive updates
  • Forcing re-initialization of effects that should run fresh
  • Clearing form state when switching between different records

When NOT to Use #key

  • Simple prop updates that components handle correctly
  • High-frequency changes without proper debouncing
  • Large component trees where the recreation cost is prohibitive
  • Preserving scroll position, focus, or selection across updates

Best Practices Checklist

  1. Use primitive values or properly serialized strings as keys
  2. Keep the scope of #key as narrow as possible
  3. Consider debouncing rapidly-changing keys
  4. Handle transition events if you need to coordinate complex animations
  5. Test that cleanup in onDestroy and effect teardowns works correctly
  6. Measure performance impact in complex components
  7. Document why #key is necessary in non-obvious cases

Conclusion

The #key block represents one of Svelte’s most elegant solutions to a common frontend challenge: forcing selective component recreation when identity changes matter more than individual prop updates. By understanding its mechanics deeply—how it destroys and recreates DOM subtrees, when transitions fire, and how cleanup functions execute—you can wield this tool effectively to build more predictable, maintainable, and performant applications.

The power of #key lies in its precision. Unlike coarse-grained solutions like remounting entire component trees, #key blocks let you target exactly which components should reset when specific values change. Combined with proper debouncing for high-frequency changes, thoughtful scope minimization, and testing of cleanup behaviors, #key blocks transform from a simple syntax feature into an architectural tool for managing component lifecycle with surgical precision.

Key Takeaways

  • #key blocks force recreation of their contents when the key expression changes, destroying the old subtree and creating a fresh instance with clean state
  • Transitions fire on key changes even when content remains in the DOM, enabling animations triggered by value changes rather than just presence/absence
  • Component state is completely reset including all $state, local variables, $effect subscriptions, and onMount/onDestroy lifecycle hooks
  • Key expressions must return primitive values or stable object references - objects/arrays should be serialized with JSON.stringify() for reliable identity checking
  • Cleanup functions always execute before recreation, ensuring proper resource disposal, event listener removal, and teardown of third-party library integrations
  • Performance cost is proportional to subtree size - wrap only the minimal necessary content, not entire component trees, to minimize recreation overhead
  • Debouncing prevents rapid recreation when keys change frequently (e.g., from text inputs) using techniques like setTimeout debounce or $derived with throttling
  • Common use cases include resetting forms, triggering entry animations on value changes, and re-initializing third-party libraries that lack reactive APIs

See Also

Topic complete
Up next: Special Elements
<svelte:body> Deep-dive into Svelte 5's `<svelte:body>` special element for global event handling, keyboard shortcuts, click-outside patterns, and runes-based reactivity.
18 min read
#lifecycle