Skip to main content

API

Imports

As well as runes, Svelte 5 introduces a handful of new things you can import, alongside existing ones like getContext, setContext and tick.

svelte

flushSync

Forces any pending effects (including DOM updates) to be applied immediately, rather than in the future. This is mainly useful in a testing context — you'll rarely need it in application code.

<script>
	import { flushSync } from 'svelte';

	let count = $state(0);
	let element;

	function onclick() {
		flushSync(() => (count += 1));

		// without `flushSync`, the DOM would be updated in the future
		console.log(element.textContent === String(count));
	}
</script>

<span bind:this={element}>{count}</span>
<button {onclick}>update</button>

mount

Instantiates a component and mounts it to the given target:

ts
import { mount } from 'svelte';
import App from './App.svelte';
const app = mount(App, {
target: document.querySelector('#app'),
props: { some: 'property' }
});

Note that unlike calling new App(...) in Svelte 4, things like effects (including onMount callbacks, and action functions) will not run during mount. If you need to force pending effects to run (in the context of a test, for example) you can do so with flushSync().

hydrate

Like mount, but will reuse up any HTML rendered by Svelte's SSR output (from the render function) inside the target and make it interactive:

ts
import { hydrate } from 'svelte';
import App from './App.svelte';
const app = hydrate(App, {
target: document.querySelector('#app'),
props: { some: 'property' }
});

As with mount, effects will not run during hydrate — use flushSync() immediately afterwards if you need them to.

unmount

Unmounts a component created with mount or hydrate:

ts
import { mount, unmount } from 'svelte';
import App from './App.svelte';
const app = mount(App, {...});
// later
unmount(app);

untrack

To prevent something from being treated as an $effect/$derived dependency, use untrack:

<script>
	import { untrack } from 'svelte';

	let { a, b } = $props();

	$effect(() => {
		// this will run when `a` changes,
		// but not when `b` changes
		console.log(a);
		console.log(untrack(() => b));
	});
</script>

createRawSnippet

An advanced API designed for people building frameworks that integrate with Svelte, createRawSnippet allows you to create snippets programmatically for use with {@render ...} tags:

ts
import { createRawSnippet } from 'svelte';
const greet = createRawSnippet((name) => {
return {
render: () => `
<h1>Hello ${name()}!</h1>
`,
setup: (node) => {
$effect(() => {
node.textContent = `Hello ${name()}!`;
});
}
};
});

The render function is called during server-side rendering, or during mount (but not during hydrate, because it already ran on the server), and must return HTML representing a single element.

The setup function is called during mount or hydrate with that same element as its sole argument. It is responsible for ensuring that the DOM is updated when the arguments change their value — in this example, when name changes:

{@render greet(name)}

If setup returns a function, it will be called when the snippet is unmounted. If the snippet is fully static, you can omit the setup function altogether.

svelte/reactivity

Svelte provides reactive SvelteMap, SvelteSet, SvelteDate and SvelteURL classes. These can be imported from svelte/reactivity and used just like their native counterparts. Demo:

<script>
	import { SvelteURL } from 'svelte/reactivity';

	const url = new SvelteURL('https://example.com/path');
</script>

<!-- changes to these... -->
<input bind:value={url.protocol} />
<input bind:value={url.hostname} />
<input bind:value={url.pathname} />

<hr />

<!-- will update `href` and vice versa -->
<input bind:value={url.href} />

svelte/events

Where possible, event handlers added with attributes like onclick use a technique called event delegation. It works by creating a single handler for each event type on the root DOM element, rather than creating a handler for each element, resulting in better performance and memory usage.

Delegated event handlers run after other event handlers. In other words, a handler added programmatically with addEventListener will run before a handler added declaratively with onclick, regardless of their relative position in the DOM (demo). It also means that calling event.stopPropagation() inside a declarative handler won't prevent the programmatic handler (created inside an action, for example) from running.

To preserve the relative order, use on rather than addEventListener (demo):

ts
import { on } from 'svelte/events';
const off = on(element, 'click', () => {
console.log('element was clicked');
});
// later, if we need to remove the event listener:
off();

on also accepts an optional fourth argument which matches the options argument for addEventListener.

svelte/server

render

Only available on the server and when compiling with the server option. Takes a component and returns an object with body and head properties on it, which you can use to populate the HTML when server-rendering your app:

ts
import { render } from 'svelte/server';
import App from './App.svelte';
const result = render(App, {
props: { some: 'property' }
});

If the css compiler option was set to 'injected', <style> elements will be included in the head.

svelte/store

In addition to the existing store-related imports such as writable, svelte/store gains two new functions: fromStore and toStore. These allow you to easily use stores and rune-based state interchangeably, even outside .svelte files.

fromStore

Takes a store and turns it into an object with a reactive (and readonly, if the store is not writable) current property.

ts
import { fromStore, get, writable } from 'svelte/store';
const store = writable(0);
const count = fromStore(store);
count.current; // 0;
store.set(1);
count.current; // 1
count.current += 1;
get(store); // 2

toStore

Creates a store from a function that returns reactive state (and, optionally, a second function that sets the state):

ts
import { toStore } from 'svelte/store';
let count = $state(0);
const store = toStore(
() => count,
(v) => (count = v)
);
store.set(1);
count; // 1

svelte/elements

Svelte provides built-in DOM types. A common use case for DOM types is forwarding props to an HTML element. To properly type your props and get full intellisense, your props interface should extend the attributes type for your HTML element:

<script lang="ts">
	import { HTMLAttributes } from 'svelte/elements';

	interface Props extends HTMLAttributes<HTMLDivElement> {
		username: string;
	}

	let { username, ...rest }: Props = $props();
</script>

<div {...rest}>
	Hi, {username}!
</div>

You can use ComponentProps<ImportedComponent>, if you wish to forward props to a Svelte component.

Svelte provides a best-effort of all the HTML DOM types that exist. If an attribute is missing from our type definitions, you are welcome to open an issue and/or a PR fixing it. For experimental attributes, you can augment the existing types locally by creating a .d.ts file:

ts
import { HTMLButtonAttributes } from 'svelte/elements';
declare module 'svelte/elements' {
export interface SvelteHTMLElements {
'custom-button': HTMLButtonAttributes;
}
// allows for more granular control over what element to add the typings to
export interface HTMLButtonAttributes {
veryexperimentalattribute?: string;
}
}
export {}; // ensure this is not an ambient module, else types will be overridden instead of augmented

The .d.ts file must be included in your tsconfig.json file. If you are using the standard "include": ["src/**/*"], this just means the file should be placed in the src directory.