Component Lifecycle

Relevant source files

• documentation/docs/01-introduction/02-getting-started.md
• documentation/docs/01-introduction/03-svelte-files.md
• documentation/docs/01-introduction/04-svelte-js-files.md
• documentation/docs/02-runes/01-what-are-runes.md
• documentation/docs/02-runes/02-$state.md
• documentation/docs/02-runes/03-$derived.md
• documentation/docs/02-runes/04-$effect.md
• documentation/docs/02-runes/05-$props.md
• documentation/docs/02-runes/07-$inspect.md
• documentation/docs/03-template-syntax/01-basic-markup.md
• documentation/docs/03-template-syntax/02-if.md
• documentation/docs/03-template-syntax/03-each.md
• documentation/docs/03-template-syntax/04-key.md
• documentation/docs/03-template-syntax/05-await.md
• documentation/docs/03-template-syntax/06-snippet.md
• documentation/docs/03-template-syntax/[email protected]
• documentation/docs/03-template-syntax/[email protected]
• documentation/docs/04-styling/04-nested-style-elements.md
• documentation/docs/06-runtime/01-stores.md
• documentation/docs/06-runtime/03-lifecycle-hooks.md
• documentation/docs/07-misc/02-testing.md
• documentation/docs/07-misc/03-typescript.md
• documentation/docs/07-misc/06-v4-migration-guide.md
• documentation/docs/07-misc/07-v5-migration-guide.md
• documentation/docs/07-misc/99-faq.md
• documentation/docs/99-legacy/00-legacy-overview.md
• documentation/docs/99-legacy/01-legacy-let.md
• documentation/docs/99-legacy/02-legacy-reactive-assignments.md
• documentation/docs/99-legacy/03-legacy-export-let.md
• documentation/docs/99-legacy/04-legacy-$$props-and-$$restProps.md
• documentation/docs/99-legacy/10-legacy-on.md
• documentation/docs/99-legacy/40-legacy-component-api.md
• packages/svelte/src/internal/client/constants.js
• packages/svelte/src/internal/client/context.js
• packages/svelte/src/internal/client/dom/blocks/async.js
• packages/svelte/src/internal/client/dom/blocks/await.js
• packages/svelte/src/internal/client/dom/blocks/boundary.js
• packages/svelte/src/internal/client/dom/blocks/css-props.js
• packages/svelte/src/internal/client/dom/blocks/each.js
• packages/svelte/src/internal/client/dom/blocks/html.js
• packages/svelte/src/internal/client/dom/blocks/if.js
• packages/svelte/src/internal/client/dom/blocks/key.js
• packages/svelte/src/internal/client/dom/blocks/snippet.js
• packages/svelte/src/internal/client/dom/blocks/svelte-component.js
• packages/svelte/src/internal/client/dom/blocks/svelte-element.js
• packages/svelte/src/internal/client/dom/blocks/svelte-head.js
• packages/svelte/src/internal/client/dom/css.js
• packages/svelte/src/internal/client/dom/elements/custom-element.js
• packages/svelte/src/internal/client/dom/elements/customizable-select.js
• packages/svelte/src/internal/client/dom/hydration.js
• packages/svelte/src/internal/client/dom/operations.js
• packages/svelte/src/internal/client/dom/reconciler.js
• packages/svelte/src/internal/client/dom/template.js
• packages/svelte/src/internal/client/proxy.js
• packages/svelte/src/internal/client/reactivity/async.js
• packages/svelte/src/internal/client/reactivity/batch.js
• packages/svelte/src/internal/client/reactivity/deriveds.js
• packages/svelte/src/internal/client/reactivity/effects.js
• packages/svelte/src/internal/client/reactivity/props.js
• packages/svelte/src/internal/client/reactivity/sources.js
• packages/svelte/src/internal/client/reactivity/store.js
• packages/svelte/src/internal/client/reactivity/types.d.ts
• packages/svelte/src/internal/client/render.js
• packages/svelte/src/internal/client/runtime.js
• packages/svelte/src/internal/client/types.d.ts
• packages/svelte/tests/runtime-legacy/samples/dynamic-element-store/main.svelte
• packages/svelte/tests/runtime-runes/samples/async-if-hydration/Child.svelte
• packages/svelte/tests/runtime-runes/samples/async-if-hydration/_config.js
• packages/svelte/tests/runtime-runes/samples/async-if-hydration/main.svelte
• packages/svelte/tests/signals/test.ts

This page documents the Svelte 5 component lifecycle as implemented in the client-side runtime. It covers the mounting, hydration, and unmounting processes, effect hierarchy management, and the boundary system for error handling.

For details on the underlying reactivity primitives, see page [4.1]. For batching and async update handling, see [4.2]. For control flow block implementations, see [4.4].

Overview: Lifecycle Phases

The component lifecycle consists of three primary phases, each managed by specific runtime functions:

1. Mounting/Hydration: Component instantiation and DOM setup or attachment
2. Execution: Reactive updates managed through effect hierarchies
3. Unmounting: Cleanup and resource deallocation

Diagram: Lifecycle Phase Transitions

Sources:
packages/svelte/src/internal/client/render.js67-152
packages/svelte/src/internal/client/reactivity/effects.js266-283

Mounting: Component Instantiation

The mount() function creates a new component instance and attaches it to the DOM. It is defined in packages/svelte/src/internal/client/render.js67-69 and performs the following sequence:

Diagram: mount() Execution Flow

The mount() function follows these steps:

1. Initialize DOM operations via init_operations() packages/svelte/src/internal/client/render.js167
2. Create root effect using component_root() which returns a cleanup function packages/svelte/src/internal/client/reactivity/effects.js266-283
3. Wrap in boundary for error handling via boundary() packages/svelte/src/internal/client/render.js176-216
4. Execute component within a context (push/pop) packages/svelte/src/internal/client/render.js182-213
5. Setup event delegation for efficient event handling packages/svelte/src/internal/client/render.js218-259
6. Register for unmounting in mounted_components WeakMap packages/svelte/src/internal/client/render.js288

Mount Options

Option	Type	Purpose
target	Element | Document | ShadowRoot	DOM node to mount into
anchor	Node (optional)	Insertion point within target
props	Record<string, any>	Component properties
events	Record<string, Function> (optional)	Event handlers
context	Map<any, any> (optional)	Context values
intro	boolean (default: true)	Whether to play intro transitions
transformError	Function (optional)	Error transformation function

Sources:
packages/svelte/src/internal/client/render.js67-290
packages/svelte/src/internal/client/reactivity/effects.js266-283

Hydration: Attaching to Server-Rendered HTML

The hydrate() function attaches a component to existing server-rendered HTML rather than creating new DOM nodes. It is defined in packages/svelte/src/internal/client/render.js96-152

Diagram: Hydration Process Flow

Hydration Markers

Server-rendered HTML includes special comment nodes that guide the hydration process:

Marker	Purpose
<!--<FileRef file-url="https://github.com/sveltejs/svelte/blob/0c7f8151/-->	HYDRATION_START - marks the beginning of component content [packages/svelte/src/constants.js#L11-L11" min=11 file-path="-->`
<!--]-->	HYDRATION_END - marks the end of component content packages/svelte/src/constants.js12
<!--<FileRef file-url="https://github.com/sveltejs/svelte/blob/0c7f8151/?-->	HYDRATION_START_ELSE - marks else/fallback branches [packages/svelte/src/constants.js#L14-L14" min=14 file-path="?-->`

During hydration, the runtime:

1. Locates markers by traversing DOM until HYDRATION_START is found packages/svelte/src/internal/client/render.js104-115
2. Sets hydration state via set_hydrating(true) and set_hydrate_node() packages/svelte/src/internal/client/render.js117-118
3. Matches existing DOM instead of creating new nodes packages/svelte/src/internal/client/dom/template.js67-69
4. Validates structure and throws HYDRATION_ERROR on mismatch packages/svelte/src/internal/client/render.js114
5. Falls back to mount if options.recover !== false packages/svelte/src/internal/client/render.js138-147

Hydration Mismatch Handling

If the client-side component structure doesn't match server-rendered HTML:

Sources:
packages/svelte/src/internal/client/render.js96-152
packages/svelte/src/internal/client/dom/hydration.js1-183
packages/svelte/src/constants.js11-15

Effect Hierarchies

Components are structured as trees of effects, where each effect can have parent and child effects. This hierarchy is central to Svelte's lifecycle management.

Diagram: Effect Tree Structure

Effect Types and Relationships

Effects are created with specific flags that determine their behavior in the hierarchy:

Effect Type	Flag	Purpose	Created By
ROOT_EFFECT	1 << 6	Top-level component effect	component_root() packages/svelte/src/internal/client/reactivity/effects.js266
BRANCH_EFFECT	1 << 5	Transparent boundary between blocks	branch() packages/svelte/src/internal/client/reactivity/effects.js419
BLOCK_EFFECT	1 << 4	Control flow blocks	block() packages/svelte/src/internal/client/reactivity/effects.js396
RENDER_EFFECT	1 << 3	DOM rendering effects	render_effect() packages/svelte/src/internal/client/reactivity/effects.js355
EFFECT	1 << 2	User-defined effects	user_effect() packages/svelte/src/internal/client/reactivity/effects.js196
MANAGED_EFFECT	1 << 24	Effects that preserve children	managed() packages/svelte/src/internal/client/reactivity/effects.js408

Parent-Child Effect Linkage

Effects maintain bidirectional links through the first, last, next, and prev properties:

Effects are linked during creation via push_effect() packages/svelte/src/internal/client/reactivity/effects.js69-78:

1. New effect sets parent to active_effect
2. Parent's last.next points to new effect
3. New effect's prev points to parent's last
4. Parent's last updated to new effect

Effect Destruction and Unlinking

When an effect is destroyed via destroy_effect() packages/svelte/src/internal/client/reactivity/effects.js494-542:

The unlink_effect() function packages/svelte/src/internal/client/reactivity/effects.js564-576 removes the effect from the doubly-linked list while maintaining the integrity of sibling connections.

Sources:
packages/svelte/src/internal/client/reactivity/effects.js69-172
packages/svelte/src/internal/client/reactivity/effects.js494-576
packages/svelte/src/internal/client/constants.js1-78

Unmounting: Component Teardown

The unmount() function destroys a component instance and cleans up all associated resources. It is defined in packages/svelte/src/internal/client/render.js318-335

Diagram: Unmount Sequence

Unmount Process

The unmount process follows these steps:

1. Lookup component in mounted_components WeakMap packages/svelte/src/internal/client/render.js319
2. Handle transitions if options.outro === true via pause_effect() packages/svelte/src/internal/client/reactivity/effects.js588-608
3. Destroy effect tree via destroy_effect() packages/svelte/src/internal/client/reactivity/effects.js494-542
4. Remove event listeners from target and document packages/svelte/src/internal/client/render.js261-280
5. Delete reference from mounted_components packages/svelte/src/internal/client/render.js322
6. Return promise that resolves after transitions complete packages/svelte/src/internal/client/render.js318-335

Resource Cleanup During Unmount

Resource Type	Cleanup Action	Code Location
Effect tree	destroy_effect() - recursive destruction	packages/svelte/src/internal/client/reactivity/effects.js494-542
DOM nodes	remove_effect_dom() - removes nodes between start and end	packages/svelte/src/internal/client/reactivity/effects.js549-557
Event listeners	removeEventListener() on target and document	packages/svelte/src/internal/client/render.js261-280
Reactions	remove_reactions() - detaches from signals	packages/svelte/src/internal/client/runtime.js416-423
Teardown functions	execute_effect_teardown()	packages/svelte/src/internal/client/reactivity/effects.js426-440
Transitions	transition.stop() on collected managers	packages/svelte/src/internal/client/reactivity/effects.js510-516

Transition-Aware Unmounting

When unmount() is called with { outro: true }, the component plays outro transitions before destruction:

The pause_effect() function packages/svelte/src/internal/client/reactivity/effects.js588-608 marks effects as INERT and collects all TransitionManager instances. Each manager's out() method is called with a callback that counts down remaining transitions. Once all transitions complete, destroy_effect() is invoked.

Sources:
packages/svelte/src/internal/client/render.js318-335
packages/svelte/src/internal/client/reactivity/effects.js588-694
packages/svelte/src/internal/client/reactivity/effects.js494-542

Context and State Management

Component Context

Each component maintains a context object that tracks its state and relationships:

The context is managed through:

• set_component_context() during effect execution
• push() and pop() for context nesting
• Automatic cleanup when effects are destroyed

Sources: packages/svelte/src/internal/client/context.js10-16 packages/svelte/src/internal/client/types.d.ts12-52