The Complete Svelte 5 Guide

Table of Contents

• What is Svelte?
• Try Svelte
• TypeScript Aside
• Single File Components
• Component Logic
• Markup Poetry
• Component Styles
• Svelte Reactivity
• Reactive State
• Deeply Reactive State
• Derived State
• Effects
• State In Functions And Classes
• Reactive Global State
• How Svelte Reactivity Works
• Why You Should Avoid Effects
• Using Template Logic
• Listening To Events
• Using Data Bindings
• Svelte Components
• Component Composition
• Transitions And Animations
• Using Third Party Libraries
• Reactive Data Structures And Utilities
• Reactive Events
• Special Elements
• Legacy Svelte
• Using Svelte With AI

What is Svelte?

If we look at the definition from the Svelte website, it says:

Svelte is a UI framework that uses a compiler to let you write breathtakingly concise components that do minimal work in the browser, using languages you already know — HTML, CSS and JavaScript.

Because Svelte is a compiled language, it can wield the same syntax of a language that’s not great at making user interfaces like JavaScript and change the semantics for a better developer experience:

<script lang="ts">
	// reactive state
	let count = $state(0)

	// reassignment updates the UI
	setInterval(() => count += 1, 1000)
</script>

<p>{count}</p>

You might think how Svelte does some crazy compiler stuff under the hood to make this work, but the output is human readable JavaScript:

function App($$anchor) {
	// create signal
	let count = state(0)

	// update signal
	setInterval(() => set(count, get(count) + 1), 1000)

	// create element
	var p = from_html(`<p> </p>`)
	var text = child(p, true)

	// update DOM when `count` changes
	template_effect(() => set_text(text, get(count)))

	// add to DOM
	append($$anchor, p)
}

In fact, Svelte’s reactivity is just based on signals! There’s nothing magical about it. You could write a basic version of Svelte by hand without using a compiler.

Just by reading the output code, you can start to understand how Svelte works. There’s no virtual DOM, or rerendering the component when state updates like in React — Svelte only updates the part of the DOM that changed.

This is what “does minimal work in the browser” means!

Svelte also has a more opinionated application framework called SvelteKit (equivalent to Next.js for React) if you need routing, server-side rendering, adapters to deploy to different platforms and so on.

Try Svelte

You can try Svelte in the browser using the Svelte Playground and follow along without having to set up anything.

If you’re a creature of comfort and prefer your development environment, you can scaffold a Vite project and pick Svelte as the option from the CLI if you run npm create vite@latest in a terminal — you’re going to need Node.js for that.

I also recommend using the Svelte for VS Code extension for syntax highlighting and code completion, or a similar extension for your editor.

TypeScript Aside

TypeScript has become table stakes when it comes to frontend development. For that reason, the examples are going to use TypeScript, but you can use JavaScript if you prefer.

If you’re unfamiliar with TypeScript, code after : usually represents a type. You can omit the types and your code will work:

// TypeScript 👍️
let items: string[] = [...]

// JavaScript 👍️
let items = [...]

Some developers prefer writing JavaScript with JSDoc comments because it gives you the same benefits of TypeScript at the cost of a more verbose syntax:

/**
 * This is a list of items.
 * @type {string[]}
 */
let items = [...]

That is completely up to you!

Single File Components

In Svelte, files ending with .svelte are called single file components because they contain the JavaScript, HTML, and CSS in a single file.

Here’s an example of a Svelte component:

<!-- logic -->
<script lang="ts">
	let title = 'Svelte'
</script>

<!-- markup -->
<h1>{title}</h1>

<!-- styles -->
<style>
	h1 {
		color: orangered;
	}
</style>

A Svelte component can only have one top-level <script> and <style> block and is unique for every component instance. A code formatter like Prettier might arrange the blocks for you, but the order of the blocks doesn’t matter.

There’s also a special <script module> block used for sharing code across component instances we’ll learn about later.

Component Logic

Your component logic goes inside the <script> tag. Since Svelte 5, TypeScript is natively supported:

<script lang="ts">
	let title = 'Svelte'
</script>

<h1>{title as string}</h1>

Later we’re going to learn how you can even define values inside your markup which can be helpful in some cases.

Markup Poetry

In Svelte, anything that’s outside the <script> and <style> blocks is considered markup:

<!-- markup -->
<h1>Svelte</h1>

You can use JavaScript expressions in the template using curly braces and Svelte is going to evalute it:

<script>
	let banana = 1
</script>

<p>There's {banana} {banana === 1 ? 'banana' : 'bananas'} left</p>

Later we’re going to learn about logic blocks like if and each to conditionally render content.

Tags with lowercase names are treated like regular HTML elements by Svelte and accept normal attributes:

<img src="image.gif" alt="Person dancing" />

You can pass values to attributes using curly braces:

<script lang="ts">
	let src = 'image.gif'
	let alt = 'Person dancing'
</script>

<img src={src} alt={alt} />

If the attribute name and value are the same, you can use a shorthand attribute:

<!-- 👍️ longhand -->
<img src={src} alt={alt} />

<!-- 👍️ shorthand -->
<img {src} {alt} />

Attributes can have expressions inside the curly braces:

<script lang="ts">
	let src = 'image.gif'
	let alt = 'Person dancing'
	let lazy = true
</script>

<img {src} {alt} loading={lazy ? 'lazy' : 'eager'} />

If you want to conditionally render attributes, don’t use && for short-circuit evaluation or empty strings. Instead, use null or undefined as the value:

<script lang="ts">
	let src = 'image.gif'
	let alt = 'Person dancing'
	let lazy = false
</script>

<!-- ⛔️ -->
<img {src} {alt} loading={lazy && 'lazy'} />
<img {src} {alt} loading={lazy ? 'lazy' : ''} />

<!-- 👍 -->
<img {src} {alt} loading={lazy ? 'lazy' : null} />
<img {src} {alt} loading={lazy ? 'lazy' : undefined} />

You can spread attributes on elements:

<script lang="ts">
	let obj = {
		src: 'image.gif',
		alt: 'Person dancing'
	}
</script>

<img {...obj} />

Component Styles

There are many ways you can style a Svelte component. 💅 I’ve heard people love inline styles with Tailwind CSS, so you could just use the style tag…I’m joking! 😄

That being said, the style tag can be useful. You can use the style attribute like in regular HTML, but Svelte also has a shorthand style: directive you can use. The only thing you can’t pass is an object:

<script lang="ts">
	let color = 'orangered'
</script>

<!-- 👍️ attribute -->
<h1 style="color: {color}">Svelte</h1>

<!-- 👍️ directive -->
<h1 style:color>Svelte</h1>

<!-- ⛔️ object -->
<h1 style={{ color }}>Svelte</h1>

You can even add important like style:color|important to override styles. The style: directive is also great for CSS custom properties:

<script lang="ts">
	let color = 'orangered'
</script>

<!-- 👍️ custom CSS property -->
<h1 style="--color: {color}">Svelte</h1>

<!-- 👍️ shorthand -->
<h1 style:--color={color}>Svelte</h1>

<style>
	h1 {
		/* custom CSS property with a default value */
		color: var(--color, #fff);
	}
</style>

Scoped Styles

Fortunately, you’re not stuck using the style attribute. Most of the time, you’re going to use the style block to define styles in your component. Those styles are scoped to the component by default:

<h1>Svelte</h1>

<!-- these styles only apply to this component -->
<style>
	h1 {
		color: orangered;
	}
</style>

Scoped styles are unique to that component and don’t affect styles in other components. If you’re using the Svelte playground, you can open the CSS output tab to view the generated CSS:

/* uniquely generated class name */
h1.svelte-ep2x9j {
	color: orangered;
}

If you want to define global styles for your app, you can import a CSS stylesheet at the root of your app:

// inside a Vite project
import { mount } from 'svelte'
import App from './App.svelte'
import './app.css'

const app = mount(App, {
  target: document.getElementById('app')!
})

export default app

You can also define global styles in components. This is useful if you have content from a content management system (CMS) that you have no control over.

Svelte has to “see” the styles in the component, so it doesn’t know they exist and warns you about removing unusued styles:

<script lang="ts">
	let content = `
		<h1>Big Banana Exposed</h1>
		<p>The gorillas inside the banana cartel speak out</p>
	`
</script>

<article>
	{@html content}
</article>

<style>
	article {
		/* ⚠️ Unused CSS selector "h1" */
		h1 {
			font-size: 48px;
		}

		/* ⚠️ Unused CSS selector "p" */
		p {
			font-size: 20px;
		}
	}
</style>

In that case, you can make the styles global by using the :global(selector) modifier:

<!-- ... -->
<style>
	article {
		:global(h1) {
			font-size: 48px;
		}

		:global(p) {
			font-size: 20px;
		}
	}
</style>

Having to use :global on every selector is tedious! Thankfully, you can nest global styles inside a :global { ... } block:

<!-- ... -->
<style>
	:global {
		article {
			h1 {
				font-size: 48px;
			}

			p {
				font-size: 20px;
			}
		}
	}
</style>

You can also have “global scoped styles” where the styles inside the :global block are scoped to the class:

<!-- ... -->
<style>
	article :global {
		h1 {
			font-size: 48px;
		}

		p {
			font-size: 20px;
		}
	}
</style>

Here’s the compiled CSS output:

article.svelte-ju1yn8 {
	h1 {
		font-size: 48px;
	}

	p {
		font-size: 20px;
	}
}

Keyframe animations are also scoped to the component. If you want to make them global, you have to prepend the keyframe name with -global-. The -global- part is removed when compiled, so you can reference the keyframe name in your app:

<style>
	@keyframes -global-animation {
		/* ... */
	}
</style>

You can use different preprocessors like PostCSS or SCSS by simply adding the lang attribute to the <style> tag with the preprocessor you want to use:

<style lang="postcss">
	<!-- ... -->
</style>

<style lang="scss">
	<!-- ... -->
</style>

These days you probably don’t need SCSS anymore, since a lot of features such as nesting and CSS variables are supported by CSS.

Dynamic Classes

You can use an expression to apply a dynamic class, but it’s tedious and easy to make mistakes:

<script lang="ts">
	let open = false
</script>

<div class="trigger {open ? 'open' : ''}">👈️</div>

<style>
	.trigger {
		display: inline-block;
		transition: all 0.2s ease;

		&.open {
			rotate: -90deg;
		}
	}
</style>

Thankfully, Svelte can helps us out here. You can use the class: directive to conditionally apply a class:

<div class="trigger" class:open>👈️</div>

You can also pass an object, array, or both to the class attribute and Svelte is going to use clsx under the hood to merge the classes:

<!-- 👍️ passing an object -->
<div class={{ trigger: true, open }}>👈️</div>

<!-- 👍️ passing an array -->
<div class={['trigger', open && 'open']}>👈️</div>

<!-- 👍️ passing an array and object -->
<div class={['trigger', { open }]}>👈️</div>

If you’re using Tailwind, this is very useful when you need to apply a bunch of classes:

<div class={['transition-transform', { '-rotate-90': open }]}>👈️</div>

You can also use data attributes to make the transition state more explicit, instead of using a bunch of classes:

<script lang="ts">
	let status = 'closed'
</script>

<div class="trigger" data-status={status}>👈️</div>

<style>
	.trigger {
		display: inline-block;
		transition: rotate 2s ease;

		&[data-status="closed"] {
			rotate: 0deg;
		}

		&[data-status="open"] {
			rotate: -90deg;
		}
	}
</style>

Svelte Reactivity

What is state?

In the context of JavaScript frameworks, application state refers to values that are essential to your application working and cause the framework to update the UI when changed.

Let’s look at a counter example:

<!-- only required for this example because of legacy mode -->
<svelte:options runes={true} />

<script lang="ts">
	let count = 0
</script>

<button onclick={() => count += 1}>
	{count}
</button>

The Svelte compiler knows that you’re trying to update the count value and warns you because it’s not reactive:

count is updated, but is not declared with $state(...). Changing its value will not correctly trigger updates.

This brings us to our first Svelte rune — the $state rune.

Reactive State

The $state rune marks a variable as reactive. Svelte’s reactivity is based on assignments. To update the UI, you just assign a new value to a reactive variable:

<script lang="ts">
	// reactive value
	let count = $state(0)
</script>

<!-- reactive assignment -->
<button onclick={() => count += 1}>
	{count}
</button>

You can open the developer tools and see that Svelte only updated the part of the DOM that changed.

The $state(...) syntax is called a rune and is part of the language. It looks like a function, but it’s only a hint to Svelte what to do with it. This means as far as TypeScript is concerned, it’s just a function:

let value = $state<Type>(...)

The three main runes we’re going to learn about are the $state, $derived, and $effect rune.

Deeply Reactive State

If you pass an array, or object to $state it becomes a deeply reactive Proxy. This lets Svelte perform granular updates when you read or write properties and avoids mutating the state directly.

For example, changing editor.content is going to update the UI in every place where it’s used:

<script lang="ts">
	let editor = $state({
		theme: 'dark',
		content: '<h1>Svelte</h1>'
	})
</script>

<textarea
	value={editor.content}
	oninput={(e) => editor.content = (e.target as HTMLTextAreaElement).value}
></textarea>

{@html editor.content}

<style>
	textarea {
		width: 100%;
		height: 200px;
	}
</style>

$state.raw

You might not want deeply reactive state where pushing to an array or updating the object would cause an update. In that case, you can use $state.raw so state only updates when you reassign it:

<script lang="ts">
	// this could be a complex object
	let editor = $state.raw({
		theme: 'dark',
		content: '<h1>Svelte</h1>'
	})
</script>

<textarea
	value={editor.content}
	oninput={(e) => {
		// ⛔️ can't be mutated
		editor.content = e.target.value

		// 👍️ reassignment
		editor = {
			...editor,
			content: e.target.value
		}
	}}
></textarea>

{@html editor.content}

<style>
	textarea {
		width: 100%;
		height: 200px;
	}
</style>

$state.snapshot

Because proxied state is deeply reactive, you could change it on accident when you pass it around, or run into a problem with some API that doesn’t expect it. In that case, you can use $state.snapshot to get the normal value from the Proxy:

function saveEditorState(editor) {
	// 💣️ oops! it doesn't like a Proxy object...
	const editorState = structuredClone(editor)
	// 👍️ normal object
	const editorState = structuredClone($state.snapshot(editor))
}

Destructuring

You can destructure deep state where you defined it — but if you destructure it anywhere else — it loses reactivity because it’s just JavaScript, so the values are evaluated when you destructure them:

<script lang="ts">
	// 👍️ reactive
	let { theme, content } = $state({
		theme: 'dark',
		content: '<h1>Svelte</h1>'
	})

	// ⛔️ not reactive
	let { theme, content } = editor
</script>

{@html content}

If you want to do this, you can use derived state!

Derived State

You can derive state from other state using the $derived rune and it’s going to reactively update:

<script lang="ts">
	let count = $state(0)
	let factor = $state(2)
	let result = $derived(count * factor)
</script>

<button onclick={() => count++}>Count: {count}</button>
<button onclick={() => factor++}>Factor: {factor}</button>

<p>{count} * {factor} = {result}</p>

Deriveds Are Lazy

Derived values only run when they’re read and are lazy evaluted which means they only update when they change and not when their dependencies change to avoid unnecessary work.

In this example, even if max depends on count, it only updates when max updates:

<script lang="ts">
	let count = $state(0)
	let max = $derived(count >= 4)

	// only logs when `max` changes
	$inspect(max)
</script>

<button onclick={() => count++} disabled={max}>
	{count}
</button>

Derived Dependency Tracking

You can pass a function to a derived without losing reactivity, because a signal only has to be read to become a dependency:

<script lang="ts">
	let count = $state(0)
	let max = $derived(limit())

	function limit() {
		return count > 4 // 📖
	}
</script>

<button onclick={() => count++} disabled={max}>
	{count}
</button>

This might sound like magic, but the only magic here is the system of signals and runtime reactivity! 🪄

The reason you don’t have to pass state to the function — unless you want to be explicit — is because signals only care where they’re read, as highlighted in the compiled output.

Not passing any arguments:

let disabled = derived(limit)

function limit() {
	return get(count) > 4 // 📖
}

Passing count as argument:

let disabled = derived(() => limit(get(count))) // 📖

function limit(count) {
	return count > 4
}

$derived.by

The $derived rune only accepts an expression by default, but you can use the $derived.by rune for a more complex derivation:

<script lang="ts">
	let cart = $state([
		{ item: '🍎', total: 10 },
		{ item: '🍌', total: 10 }
	])
	let total = $derived.by(() => {
		let sum = 0
		for (let item of cart) {
			sum += item.total
		}
		return sum
	})
</script>

<p>Total: {total}€</p>

Svelte recommends you keep deriveds free of side-effects. You can’t update state inside of deriveds to protect you from unintended side-effects:

<script lang="ts">
	let count = $state(0)
	let double = $derived.by(() => {
		// ⛔️ error
		count++
	})
</script>

Destructuring From Deriveds

Going back to a previous example, you can also use derived state to keep reactivity when using destructuring:

<script lang="ts">
	let editor = $state({
		theme: 'dark',
		content: '<h1>Svelte</h1>'
	})

	// ⛔️ not reactive
	let { theme, content } = editor

	// 👍️ reactive
	let { theme, content } = $derived(editor)
</script>

{@html content}

Effects

The last main rune you should know about is the $effect rune.

Effects are functions that run when the component is added to the DOM and when their dependencies change.

State that is read inside of an effect will be tracked:

<script lang="ts">
	let count = $state(0)

	$effect(() => {
		// 🕵️ tracked
		console.log(count)
	})
</script>

<button onclick={() => count++}>Click</button>

Values are only tracked if they’re read.

Here if condition is true, then condition and count are going to be tracked. If condition is false, then the effect only reruns when condition changes:

<script lang="ts">
	let count = $state(0)
	let condition = $state(false)

	$effect(() => {
		if (condition) {
			console.log(count) // 📖
		}
	})
</script>

<button onclick={() => condition = !condition}>Toggle</button>
<button onclick={() => count++}>Click</button>

Svelte provides an untrack function if you don’t want to track the state:

<script lang="ts">
	import { untrack } from 'svelte'

	let a = $state(0)
	let b = $state(0)

	$effect(() => {
		// ⛔️ only runs when `b` changes
		console.log(untrack(() => a) + b)
	})
</script>

<button onclick={() => a++}>A</button>
<button onclick={() => b++}>B</button>

You can return a function from the effect callback, which reruns when the effect dependencies change, or when the component is removed from the DOM:

<script lang="ts">
	let count = $state(0)
	let delay = $state(1000)

	$effect(() => {
		// 🕵️ only `delay` is tracked
		const interval = setInterval(() => count++, delay)
		// 🧹 clear interval every update
		return () => clearInterval(interval)
	})
</script>

<button onclick={() => delay *= 2}>+</button>
<span>{count}</span>
<button onclick={() => delay /= 2}>-</button>

Effect Dependency Tracking

When it comes to deeply reactive state, effects only rerun when the object it reads changes and not its properties:

<script lang="ts">
	let obj = $state({ current: 0 })

	$effect(() => {
		// doesn't run if property changes
		console.log(obj)
	})

	$effect(() => {
		// you have to track the property
		console.log(obj.current)
	})
</script>

There are ways around it though! 🤫

You can use JSON.stringify, $state.snapshot, or the $inspect rune to react when the object properties change. The save function could be some external API used to save the data:

<script lang="ts">
	let obj = $state({ current: 0 })

	$effect(() => {
		JSON.stringify(obj) // 👍️ tracked
		save(obj)
	})

	$effect(() => {
		$state.snapshot(obj) // 👍️ tracked
		save(obj)
	})

	$effect(() => {
		$inspect(obj) // 👍️ tracked
		save(obj)
	})
</script>

When Not To Use Effects

Don’t use effects to synchronize state because Svelte queues your effects and runs them last. Using effects to synchronize state can cause unexpected behavior like state being out of sync:

<script lang="ts">
	let count = $state(0)
	let double = $state(0)

	$effect(() => {
		// effects run last
		double = count * 2
	})
</script>

<button onclick={() => {
	count++ // 1
	console.log(double) // ⚠️ 0
}}>
	{double}
</button>

Always derive state when you can instead:

<script lang="ts">
	let count = $state(0)
	let double = $derived(count * 2)
</script>

<button onclick={() => {
	count++ // 1
	console.log(double) // 👍️ 2
}}>
	{double}
</button>

If you don’t want to track values, you can use the onMount lifecycle function instead of an effect:

<script lang="ts">
	import { onMount } from 'svelte'

	onMount(() => {
		console.log('Component added 👋')
		return () => console.log('🧹 Component removed')
	})
</script>

When To Use Effects

Effects should be a last resort when you have to synchronize with an external system that doesn’t understand Svelte’s reactivity. They should only be used for side-effects like fetching data from an API, or working with the DOM directly.

In this example, we’re using the Pokemon API and getAbortSignal from Svelte to avoid making a bunch of requests when doing a search:

<script lang="ts">
	import { getAbortSignal } from 'svelte'

	let pokemon = $state('charizard')
	let image = $state('')

	async function getPokemon(pokemon: string) {
		const baseUrl = 'https://pokeapi.co/api/v2/pokemon'
		const response = await fetch(`${baseUrl}/${pokemon}`, {
			// aborts when derived and effect reruns
			signal: getAbortSignal()
		})
		if (!response.ok) throw new Error('💣️ oops!')
		return response.json()
	}

	$effect(() => {
		getPokemon(pokemon).then(data => {
			image = data.sprites.front_default
		})
	})
</script>

<input
	type="search"
	placeholder="Enter Pokemon name"
	oninput={(e) => pokemon = (e.target as HTMLInputElement).value}
/>
<img src={image} alt={pokemon} />

$effect.pre

Your effects run after the DOM updates in a microtask, but sometimes you might need to do work before the DOM updates like measuring an element, or scroll position — in that case, you can use the $effect.pre rune.

A great example is the GSAP Flip plugin for animating view changes when you update the DOM. It needs to measure the position, size, and rotation of elements before and after the DOM update.

In this example, we measure the elements before the DOM updates, and use tick to wait for the DOM update:

<script lang="ts">
	import { gsap } from 'gsap'
	import { Flip } from 'gsap/Flip'
	import { tick } from 'svelte'

	gsap.registerPlugin(Flip)

	let items = $state([...Array(20).keys()])

	$effect.pre(() => {
		// track `items` as a dependency
		items
		// measure elements before the DOM updates
		const state = Flip.getState('.item')
		// wait for the DOM update
		tick().then(() => {
			// do the FLIP animation
			Flip.from(state, { duration: 1, stagger: 0.01, ease: 'power1.inOut' })
		})
	})

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

<div class="container">
	{#each items as item (item)}
		<div class="item">{item}</div>
	{/each}
</div>

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

<style>
	.container {
		width: 600px;
		display: grid;
		grid-template-columns: repeat(5, 1fr);
		gap: 0.5rem;
		color: orangered;
		font-size: 3rem;
		font-weight: 700;
		text-shadow: 2px 2px 0px #000;

		.item {
			display: grid;
			place-content: center;
			aspect-ratio: 1;
			background-color: #222;
			border: 1px solid #333;
			border-radius: 1rem;
		}
	}

	button {
		margin-top: 1rem;
		font-size: 2rem;
	}
</style>

tick is a useful lifecyle function that schedules a task to run in the next microtask when all the work is done, and before the DOM updates.

State In Functions And Classes

So far, we only used runes at the top-level of our components, but you can use state, deriveds, and effects inside functions and classes.

You can use runes in a JavaScript module by using the .svelte.js or .svelte.ts extension to tell Svelte that it’s a special file, so it doesn’t have to check every file for runes.

In this example, we’re creating a createCounter function that holds the count value and returns a increment and decrement function:

export function createCounter(initial: number) {
	let count = $state(initial)

	$effect(() => {
		console.log(count)
	})

	const increment = () => count++
	const decrement = () => count--

	return {
		get count() { return count },
		set count(v) { count = v },
		increment,
		decrement
	}
}

Here’s how it’s used inside of a Svelte component:

<script lang="ts">
	import { createCounter } from './counter.svelte'

	const counter = createCounter(0)
</script>

<button onclick={counter.decrement}>-</button>
<span>{counter.count}</span>
<button onclick={counter.increment}>+</button>

Reactive Properties

You’re probably wondering, what’s the deal with the get and set methods?

Those are called getters and setters, and they create accessor properties which let you define custom behavior when you read and write to a property.

They’re just part of JavaScript, and you could use functions instead:

export function createCounter(initial: number) {
	let count = $state(initial)

	const increment = () => count++
	const decrement = () => count--

	return {
		count() { return count },
		setCount(v: number) { count = v },
		increment,
		decrement
	}
}

You could return a tuple instead to make the API nicer and destructure the read and write functions like [count, setCount] = createCounter(0).

As you can see, the syntax is not as nice compared to using accessors, since you have to use functions everywhere:

<script lang="ts">
	import { createCounter } from './counter.svelte'

	const counter = createCounter(0)
</script>

<!-- using functions -->
<button onclick={() => counter.setCurrent(counter.count() + 1)}>
	{counter.count()}
</button>

<!-- using accessors -->
<button onclick={() => counter.count++}>
	{counter.count}
</button>

Reactive Containers

The accessor syntax looks a lot nicer! 😄 You might be wondering, can’t you just return state from the function?

export function createCounter(initial: number) {
	let count = $state(initial)
	// ⛔️ this doesn't work
	return count
}

The reason this doesn’t work is because state is just a regular value. It’s not some magic reactive container. If you want something like that, you could return deeply reactive proxied state:

export function createCounter(initial: number) {
	let count = $state({ current: initial })
	// 👍️ proxied state
	return count
}

You can create a reactive container yourself if you want:

// reactive container utility
export function reactive<T>(initial: T) {
	let value = $state<{ current: T }>({ current: initial })
	return value
}

export function createCounter(initial: number) {
	// reactive container
	let count = reactive(initial)

	const increment = () => count.current++
	const decrement = () => count.current--

	return { count, increment, decrement }
}

Even destructuring works, since count is not just a regular value:

<script lang="ts">
	import { createCounter } from './counter.svelte'

	const { count } = createCounter(0)
</script>

<button onclick={() => count.current++}>
	{count.current}
</button>

That seems super useful…so why doesn’t Svelte provide this utility?

It’s mostly because it’s a few lines of code, but another reason is classes. If you use state inside classes, you get extra benefits which you don’t get using functions.

Svelte turns any class fields declared with state into private fields with matching get/set methods, unless you declare them yourself:

export class Counter {
	constructor(initial: number) {
		// turned into `get` and `set` methods
		this.count = $state(initial)
	}

	increment() {
		this.count++
	}

	decrement() {
		this.count--
	}
}

If you look at the output, you would see something like this:

class Counter {
	#count
	get count() { ... }
	set count(v) { ... }
}

There’s only one gotcha with classes and it’s how this works.

For example, using a method like counter.increment inside onclick doesn’t work, because this refers to where it was called:

<script lang="ts">
	import { Counter } from './counter.svelte'

	const counter = new Counter(0)
</script>

<button onclick={counter.decrement}>-</button>
<span>{counter.count}</span>
<button onclick={counter.increment}>+</button>

You can see it for yourself:

increment() {
	console.log(this) // button
	this.count++
}

decrement() {
	console.log(this) // button
	this.count--
}

You either have to pass an anonymous function like () => counter.increment() to onclick, or define the methods using arrow functions that don’t bind their own this:

increment = () =>
	console.log(this) // class
	this.current++
}

decrement = () => {
	console.log(this) // class
	this.current--
}

The only downside with arrow functions is that you’re creating a new function every time time you call it, but everything works as expected.

Passing State Into Functions And Classes

Because state is a regular value, it loses reactivity when you pass it into a function or a class.

In this example, we pass count to a Doubler class to double the value when count updates. However, it’s not reactive since count is a regular value:

<script lang="ts">
	class Doubler {
		constructor(count: number) {
			this.current = $derived(count * 2) // 0 * 2
		}
	}

	let count = $state(0)
	const double = new Doubler(count) // 0
</script>

<button onclick={() => count++}>
	{double.current}
</button>

Svelte even gives you a warning with a hint:

This reference only captures the initial value of count. Did you mean to reference it inside a closure instead?

To get the latest count value, we can pass a function instead:

<script lang="ts">
	class Doubler {
		constructor(count: () => number) {
			this.value = $derived(count() * 2) // () => get(count) * 2
		}
	}

	let count = $state(0)
	const doubler = new Doubler(() => count) // () => get(count)
</script>

<button onclick={() => count++}>
	{doubler.value}
</button>

You could use the reactive utility from before! Let’s use a class version this time:

<script lang="ts">
	class Reactive<T> {
		constructor(initial: T) {
			this.current = $state<T>(initial)
		}
	}

	class Doubler {
		constructor(count: Reactive<number>) {
			this.current = $derived(count.current * 2)
		}
	}

	const count = new Reactive(0)
	const double = new Doubler(count)
</script>

<button onclick={() => count.current++}>
	{double.current}
</button>

Runes are reactive primitives that give you the flexibility to create your own reactivity system.

Reactive Global State

Creating global reactive state in Svelte is simple as exporting deep state from a module, like a config which can be used across your app:

interface Config {
	theme: 'light' | 'dark'
}

export const config = $state<Config>({ theme: 'dark' })

export function toggleTheme() {
	config.theme = config.theme === 'light' ? 'dark' : 'light'
}

<script>
	import { config, toggleTheme } from './config.svelte'
</script>

<button onclick={toggleTheme}>
	{config.theme}
</button>

You could use a function, or a class for the config:

type Themes = 'light' | 'dark'

class Config {
	theme = $state<Themes>('dark')

	toggleTheme() {
		this.theme = this.theme === 'light' ? 'dark' : 'light'
	}
}

export const config = new Config()

It doesn’t matter if you use functions or classes, as long as you understand how Svelte reactivity works.

How Svelte Reactivity Works

I believe that understanding how something works gives you greater enjoyment in life by being more competent at what you do.

I mentioned how Svelte uses signals for reactivity, but so do many other frameworks like Angular, Solid, Vue, and Qwik. There’s even a proposal to add signals to JavaScript itself.

So far we learned that assignments cause updates in Svelte. There’s nothing special about = though! It just creates a function call to update the value:

<script lang="ts">
	let value = $state('🍎')
	value = '🍌' // set(value, '🍌')
</script>

<!-- how does this get updated? -->
{value}

A signal is just a container that holds a value and subscribers that are notified when that value updates, so it doesn’t do anything on its own:

function createSignal(value) {
	const signal = {
		value,
		subscribers: new Set()
	}
	return signal
}

You need effects to react to signals and effects are just functions that run when a signal updates.

That’s how Svelte updates the DOM by compiling your template into effects. This is referred to as a tracking context:

<!-- template_effect(() => set_text(text, get(value))) -->
{value}

Everything starts with a root effect and your component is a nested effect inside of it. This way, Svelte can keep track of effects for cleanup.

When the effect runs, it invokes the callback function and sets it as the active effect in some variable:

let effect = null

function template_effect(fn) {
	// set active effect
	effect = fn
}

The magic happens when you read a signal inside of an effect. When value is read, it adds the active effect as a subscriber:

let effect = fn

function get(signal) {
	// add effect to subscribers
	signal.subscribers.add(effect)
	// return value
	return signal.value
}

Later, when you write to count it notifies the subscribers and recreates the dependency graph when it reads the signal inside the effect:

function set(signal, value) {
	// update signal
	signal.value = value
	// notify subscribers
	signal.subscribers.forEach(effect => effect())
}

This is oversimplified, but it happens every update and that’s why it’s called runtime reactivity, because it happens as your code runs!

Svelte doesn’t compile reactivity, it only compiles the implementation details. That’s how you can use signals like a regular value. In other frameworks, you always have to read and write them using functions, or accessors.

Deriveds are also effects that track their own dependencies and return a signal. You can pass a function with state inside to a derived, and it’s tracked when it’s read inside like an effect:

<script lang="ts">
	let value = $state('🍎')
	let code = $derived(getCodePoint())

	function getCodePoint() {
		// `value` is read inside derived effect
		return value.codePointAt(0).toString(16)
	}

	value = '🍌'
</script>

<!-- `code` is read inside template effect -->
{code}

I want to emphasize how $state is not some magic reactive container, but a regular value; which is why you need a function or a getter to get the latest value when the effect reruns — unless you’re using deep state.

If emoji.code was a regular value and not a getter, then the effect would always return the same value, even though it reacts to the change:

<script lang="ts">
	class Emoji {
		constructor(emoji: string) {
			// turned into `get` and `set` methods
			this.current = $state(emoji)
			this.code = $derived(this.current.codePointAt(0).toString(16))
		}
	}

	const emoji = new Emoji('🍎')
	emoji.current = '🍌'
</script>

<!-- template_effect(() => set_text(text, emoji.code)) -->
{emoji.code}

As the React people love to say, “it’s just JavaScript!” 😄

Why You Should Avoid Effects

I don’t want to scare you from using effects. Honestly, it’s not a big deal if you sometimes use effects when you shouldn’t.

The problem is that it’s easy to overcomplicate your code with effects, because it seems like the right thing to do.

In this example, I have a counter value I want to read and write using the Web Storage API each time it updates. That’s a side-effect! It seems resonable to use an effect:

class Counter {
	constructor(initial: number) {
		this.count = $state(initial)

		$effect(() => {
			const savedCount = localStorage.getItem('count')
			if (savedCount) this.count = parseInt(savedCount)
		})

		$effect(() => {
			localStorage.setItem('count', this.count.toString())
		})
	}
}

The problem only arises if you create the counter outside the component initialization phase:

export const counter = new Counter(0)

Oops! Immediately, there’s an error:

effect_orphan $effect can only be used inside an effect (e.g. during component initialisation).

In the previous section we learned that everything starts with a root effect, so Svelte can run the teardown logic for nested effects when the component is removed.

In this case, you’re trying to create an effect outside that root effect, which is not allowed.

Svelte provides an advanced $effect.root rune to create your own root effect, but now you have to run the cleanup manually:

class Counter {
	#cleanup

	constructor(initial: number) {
		this.count = $state(initial)

		// manual cleanup 😮‍💨
		this.cleanup = $effect.root(() => {
			$effect(() => {
				const savedCount = localStorage.getItem('count')
				if (savedCount) this.count = parseInt(savedCount)
			})

			$effect(() => {
				localStorage.setItem('count', this.count.toString())
			})

			return () => console.log('🧹 cleanup')
		})
	}

	destroy() {
		this.#cleanup()
	}
}

Then you learn about the $effect.tracking rune used to know if you’re inside a tracking context like the effect in your template, so maybe that’s it:

class Counter {
	constructor(initial: number) {
		this.count = $state(initial)

		if ($effect.tracking()) {
			$effect(() => {
				const savedCount = localStorage.getItem('count')
				if (savedCount) this.count = parseInt(savedCount)
			})

			$effect(() => {
				localStorage.setItem('count', this.count.toString())
			})
		}
	}
}

But there’s another problem! The effect is never going to run when the counter is created because you’re not inside a tracking context. 😩

It would make more sense to move the effect where you read the value — this way, it’s read inside of a tracking context like the template effect:

export class Counter {
	constructor(initial: number) {
		this.#count = $state(initial)
	}

	get count() {
		if ($effect.tracking()) {
			$effect(() => {
				const savedCount = localStorage.getItem('count')
				if (savedCount) this.#count = parseInt(savedCount)
			})
		}
		return this.#count
	}

	set count(v: number) {
		localStorage.setItem('count', v.toString())
		this.#count = v
	}
}

There’s another problem…

Each time we read the value, we’re creating an effect! 😱 Alright, that’s a simple fix. We can use a variable to track if we already ran the effect:

export class Counter {
	#first = true

	constructor(initial: number) {
		this.#count = $state(initial)
	}

	get count() {
		if ($effect.tracking()) {
			$effect(() => {
				if (!this.#first) return
				const savedCount = localStorage.getItem('count')
				if (savedCount) this.#count = parseInt(savedCount)
				this.#first = false
			})
		}
		return this.#count
	}

	set count(v: number) {
		localStorage.setItem('count', v.toString())
		this.#count = v
	}
}

The point I want to make is that none of this is necessary, and you can make everything simpler by doing side-effects inside event handlers like onclick instead of using effects:

export class Counter {
	#first = true

	constructor(initial: number) {
		this.#count = $state(initial)
	}

	get count() {
		if (this.#first) {
			const savedCount = localStorage.getItem('count')
			if (savedCount) this.#count = parseInt(savedCount)
			this.#first = false
		}
		return this.#count
	}

	set count(v: number) {
		localStorage.setItem('count', v.toString())
		this.#count = v
	}
}

Unless you know what you’re doing — if you catch yourself using advanced runes like $effect.root or $effect.tracking, you’re doing something wrong.

Using Template Logic

HTML doesn’t have conditionals or loops, but Svelte has control flow blocks ranging from {#if ...}, {#each ...} to data loading blocks like {#await ...}.

Using Conditionals

In Svelte, you can use the {#if ...} block to conditionally render content:

<script lang="ts">
	type Status = 'loading' | 'success' | 'error'

	let status = $state<Status>('loading')
</script>

{#if status === 'loading'}
	<p>Loading...</p>
{:else if status === 'success'}
	<p>Success!</p>
{:else if status === 'error'}
	<p>Error</p>
{:else}
	<p>Impossible state</p>
{/if}

Looping Over Data

To loop over a list of items, you use the {#each ...} block:

<script lang="ts">
	let todos = $state([
		{ id: 1, text: 'Todo 1', done: false },
		{ id: 2, text: 'Todo 2', done: false },
		{ id: 3, text: 'Todo 3', done: false },
		{ id: 4, text: 'Todo 4', done: false }
	])
</script>

<ul>
	{#each todos as todo}
		<li>
			<input checked={todo.done} type="checkbox" />
			<span>{todo.text}</span>
		</li>
	{:else}
		<p>No items</p>
	{/each}
</ul>

You can destructure the items values you’re iterating over, get the current item index and provide a key, so Svelte can keep track of changes:

<ul>
	{#each todos as { id, text, done }, i (id)}
		<li>
			<input checked={done} type="checkbox" />
			<span style:color={i % 2 === 0 ? 'orangered' : ''}>{text}</span>
		</li>
	{/each}
</ul>

You can omit the as part inside the {#each ...} block if you just want to loop over an arbitrary amount of items to create a grid for example:

<div class="grid">
	{#each Array(10), row}
		{#each Array(10), col}
			<div class="cell">{row},{col}</div>
		{/each}
	{/each}
</div>

<style>
	.grid {
		max-width: 400px;
		display: grid;
		grid-template-columns: repeat(10, 1fr);
		gap: 0.5rem;

		.cell {
			padding: 1rem;
			border: 1px solid #ccc;
		}
	}
</style>

You can loop over any iterable that works with Array.from from a Map and Set object, to generators:

<script lang="ts">
	let itemsMap = new Map([
		['🍎', 'apple'],
		['🍌', 'banana'],
	])

	let itemsSet = new Set(['🍎', '🍌'])

	function* itemsGenerator() {
		yield '🍎'
		yield '🍌'
	}
</script>

<ul>
	{#each itemsMap as [key, value]}
		<li>{key}: {value}</li>
	{/each}
</ul>

<ul>
	{#each itemsSet as item}
		<li>{item}</li>
	{/each}
</ul>

<ul>
	{#each itemsGenerator() as item}
		<li>{item}</li>
	{/each}
</ul>

Svelte even has reactive versions of built-in JavaScript objects, which we’re going to look at later.

Asynchronous Data Loading

Previously, we fetched some pokemon data inside of an effect, but we haven’t handled the loading, error, or success state.

Svelte has an {#await ...} block for dealing with promises which handles loading, error, and success states:

<script lang="ts">
	async function getPokemon(pokemon: string) {
		const baseUrl = 'https://pokeapi.co/api/v2/pokemon'
		const response = await fetch(`${baseUrl}/${pokemon}`)
		if (!response.ok) throw new Error('💣️ oops!')
		let { name, sprites } = await response.json()
		return { name, image: sprites['front_default'] }
	}
</script>

{#await getPokemon('charizard')}
	<p>loading...</p>
{:then pokemon}
	<p>{pokemon.name}</p>
	<img src={pokemon.image} alt={pokemon.name} />
{:catch error}
	<p>{error.message}</p>
{/await}

You can omit the catch block if you don’t care about errors, and the initial block if you only care about the result:

{#await getPokemon('charizard') then pokemon}
	<p>{pokemon.name}</p>
	<img src={pokemon.image} alt={pokemon.name} />
{/await}

Asynchronous Svelte Aside

In the near future, you’re going to be able to await a promise directly in a Svelte component. You can try it today by enabling the experimental async flag in your Svelte config:

export default {
	compilerOptions: {
		experimental: {
			async: true
		}
	}
}

At the moment you have to create a boundary at the root of your app, or where you want to use the await keyword:

<script lang="ts">
	let { children } = $props()
</script>

<svelte:boundary>
	{#snippet pending()}
		<!-- only shows when the component is added -->
		<p>loading...</p>
	{/snippet}

	{@render children?.()}
</svelte:boundary>

Then inside of a component, you can use the await keyword in the script block, or template:

<script lang="ts">
	// same Pokemon API as before
	import { getPokemon } from './pokemon.ts'

	let pokemon = await getPokemon('charizard')
</script>

<p>{pokemon.name}</p>
<img src={pokemon.image} alt={pokemon.name} />

You can use the $effect.pending rune to show a loading state:

<!-- shows when loading new data -->
{#if $effect.pending()}
	<p>loading...</p>
{:else}
	<p>{(await pokemon).name}</p>
	<img src={(await pokemon).image} alt={(await pokemon).name} />
{/if}

SvelteKit takes this even further with remote functions, where you can fetch data from a server by invoking a function on the client.

Recreating Elements

You can use the {#key ...} block to recreate elements when state updates. This is useful for replaying transitions, which we’re going to learn about later:

<script lang="ts">
	import { fade } from 'svelte/transition'

	let value = $state(0)
</script>

{#key value}
	<div in:fade>👻</div>
{/key}

<button onclick={() => value++}>Spook</button>

Local Constants

You can use the @const tag to define block-scoped readonly local constants in the Svelte template.

Local constants can only be defined as a child of blocks like {#if ...}, {#else ...}, {#await ...}, and <Component />.

In this example, we can destructure text and done from the todo object while keeping the original reference:

<ul>
	{#each todos as todo}
		{@const { text, done: checked } = todo}
		<li>
			<input {checked} type="checkbox" />
			<span>{text}</span>
		</li>
	{/each}
</ul>

In this example, we’re creating a SVG grid of squares using local constants to keep everything organized and legible:

<script lang="ts">
	let size = 800
	let tiles = 8
</script>

<svg width={size} height={size}>
	{#each Array(tiles), col}
		{#each Array(tiles), row}
			{@const tile = size / tiles}
			{@const x = col * tile}
			{@const y = row * tile}
			{@const width = tile}
			{@const height = tile}
			{@const fill = (col + row) % 2 === 0 ? 'orangered' : 'white'}
			<rect {x} {y} {width} {height} {fill} />
		{/each}
	{/each}
</svg>

Listening To Events

You can listen to DOM events by adding attributes that start with on to elements. In the case of a mouse click, you would add the onclick attribute to a <button> element:

<script lang="ts">
	function onclick() {
		console.log('clicked')
	}
</script>

<!-- using an inline function -->
<button onclick={() => console.log('clicked')}>Click</button>

<!-- passing a function -->
<button onclick={onclick}>Click</button>

<!-- using the shorthand -->
<button {onclick}>Click</button>

You can spread events, since they’re just attributes:

<script lang="ts">
	const events = {
		onclick: () => console.log('clicked'),
		ondblclick: () => console.log('double clicked')
	}
</script>

<button {...events}>Click</button>

This example uses the onmousemove event to update the mouse position:

<script lang="ts">
	let mouse = $state({ x: 0, y: 0 })

	// the event is automatically passed
	function onmousemove(e: MouseEvent) {
		mouse.x = e.clientX
		mouse.y = e.clientY
	}
</script>

<div {onmousemove}>
	The mouse position is {mouse.x} x {mouse.y}
</div>

<style>
	div {
		width: 100%;
		height: 100%;
	}
</style>