Skip to main content
SvelteLegacy APIs

Imperative component API

In Svelte 3 and 4, the API for interacting with a component is different than in Svelte 5. Note that this page does not apply to legacy mode components in a Svelte 5 application.

Creating a component

const const component: anycomponent = new Component(options);

A client-side component — that is, a component compiled with generate: 'dom' (or the generate option left unspecified) is a JavaScript class.

import 
type App = SvelteComponent<Record<string, any>, any, any>
const App: LegacyComponentType
App from './App.svelte';

const const app: SvelteComponent<Record<string, any>, any, any>app = new new App(o: ComponentConstructorOptions): SvelteComponentApp({
	ComponentConstructorOptions<Record<string, any>>.target: Document | Element | ShadowRoottarget: var document: Document
MDN Reference


document.Document.body: HTMLElement
Specifies the beginning and end of the document body.


MDN Reference


body,
	ComponentConstructorOptions<Record<string, any>>.props?: Record<string, any> | undefinedprops: {
		// assuming App.svelte contains something like
		// `export let answer`:
		answer: numberanswer: 42
	}
});

The following initialisation options can be provided:

option default description
target none An HTMLElement or ShadowRoot to render to. This option is required
anchor null A child of target to render the component immediately before
props {} An object of properties to supply to the component
context new Map() A Map of root-level context key-value pairs to supply to the component
hydrate false See below
intro false If true, will play transitions on initial render, rather than waiting for subsequent state changes

Existing children of target are left where they are.

The hydrate option instructs Svelte to upgrade existing DOM (usually from server-side rendering) rather than creating new elements. It will only work if the component was compiled with the hydratable: true option. Hydration of <head> elements only works properly if the server-side rendering code was also compiled with hydratable: true, which adds a marker to each element in the <head> so that the component knows which elements it’s responsible for removing during hydration.

Whereas children of target are normally left alone, hydrate: true will cause any children to be removed. For that reason, the anchor option cannot be used alongside hydrate: true.

The existing DOM doesn’t need to match the component — Svelte will ‘repair’ the DOM as it goes.

index
import 
type App = SvelteComponent<Record<string, any>, any, any>
const App: LegacyComponentType
App from './App.svelte';

const const app: SvelteComponent<Record<string, any>, any, any>app = new new App(o: ComponentConstructorOptions): SvelteComponentApp({
	ComponentConstructorOptions<Record<string, any>>.target: Document | Element | ShadowRoottarget: var document: Document
MDN Reference


document.ParentNode.querySelector<Element>(selectors: string): Element | null (+4 overloads)
Returns the first element that is a descendant of node that matches selectors.


MDN Reference


querySelector('#server-rendered-html'),
	ComponentConstructorOptions<Record<string, any>>.hydrate?: boolean | undefinedhydrate: true
});

In Svelte 5+, use mount instead

$set

component.$set(props);

Programmatically sets props on an instance. component.$set({ x: 1 }) is equivalent to x = 1 inside the component’s <script> block.

Calling this method schedules an update for the next microtask — the DOM is not updated synchronously.

component.$set({ answer: numberanswer: 42 });

In Svelte 5+, use $state instead to create a component props and update that

let 
module props
let props: {
    answer: number;
}
props = 
function $state<{
    answer: number;
}>(initial: {
    answer: number;
}): {
    answer: number;
} (+1 overload)
namespace $state
Declares reactive state.


Example:


let count = $state(0);
https://svelte.dev/docs/svelte/$state


@paraminitial The initial value
$state({ answer: numberanswer: 42 });
const const component: anycomponent = mount(Component, { 
props: {
    answer: number;
}
props });
// ...

module props
let props: {
    answer: number;
}
props.answer: numberanswer = 24;

$on

component.$on(ev, callback);

Causes the callback function to be called whenever the component dispatches an event.

A function is returned that will remove the event listener when called.

const const off: anyoff = component.$on('selected', (event: anyevent) => {
	var console: Consoleconsole.Console.log(...data: any[]): void
MDN Reference


log(event: anyevent.detail.selection);
});

const off: anyoff();

In Svelte 5+, pass callback props instead

$destroy

component.$destroy();

Removes a component from the DOM and triggers any onDestroy handlers.

In Svelte 5+, use unmount instead

Component props

component.prop;
module componentcomponent.component.prop: anyprop = value;

If a component is compiled with accessors: true, each instance will have getters and setters corresponding to each of the component’s props. Setting a value will cause a synchronous update, rather than the default async update caused by component.$set(...).

By default, accessors is false, unless you’re compiling as a custom element.

var console: Consoleconsole.Console.log(...data: any[]): void
MDN Reference


log(component.count);
component.count += 1;

In Svelte 5+, this concept is obsolete. If you want to make properties accessible from the outside, export them

Server-side component API

const const result: anyresult = Component.render(...)

Unlike client-side components, server-side components don’t have a lifespan after you render them — their whole job is to create some HTML and CSS. For that reason, the API is somewhat different.

A server-side component exposes a render method that can be called with optional props. It returns an object with head, html, and css properties, where head contains the contents of any <svelte:head> elements encountered.

You can import a Svelte component directly into Node using svelte/register.

var require: NodeJS.Require
(id: string) => any
Used to import modules, JSON, and local files.


@sincev0.1.13
require('svelte/register');

const const App: anyApp = 
var require: NodeJS.Require
(id: string) => any
Used to import modules, JSON, and local files.


@sincev0.1.13
require('./App.svelte').default;

const { const head: anyhead, const html: anyhtml, const css: anycss } = const App: anyApp.render({
	answer: numberanswer: 42
});

The .render() method accepts the following parameters:

parameter default description
props {} An object of properties to supply to the component
options {} An object of options

The options object takes in the following options:

option default description
context new Map() A Map of root-level context key-value pairs to supply to the component 
const { const head: anyhead, const html: anyhtml, const css: anycss } = App.render(
	// props
	{ answer: numberanswer: 42 },
	// options
	{
		context: Map<string, string>context: new 
var Map: MapConstructor
new <string, string>(iterable?: Iterable<readonly [string, string]> | null | undefined) => Map<string, string> (+3 overloads)
Map([['context-key', 'context-value']])
	}
);

In Svelte 5+, use render instead

Edit this page on GitHub llms.txt

previous next
<svelte:self>