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 componentconst component: any = new Componentany(optionsany);

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

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

const appconst app: SvelteComponent<Record<string, any>, any, any> = new App(alias) new App(o: ComponentConstructorOptions): SvelteComponent
import App({
	target(property) ComponentConstructorOptions<Record<string, any>>.target: Document | Element | ShadowRoot: documentvar document: Documentwindow.document returns a reference to the document contained in the window.
MDN Reference
.body(property) Document.body: HTMLElementThe Document.body property represents the  or  node of the current document, or null if no such element exists.
MDN Reference
,
	props(property) ComponentConstructorOptions<Record<string, any>>.props?: Record<string, any> | undefined: {
		// assuming App.svelte contains something like		// `export let answer`:		answer(property) answer: number: 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 App(alias) type App = SvelteComponent<Record<string, any>, any, any>
(alias) const App: LegacyComponentType
import App from './App.svelte';

const appconst app: SvelteComponent<Record<string, any>, any, any> = new App(alias) new App(o: ComponentConstructorOptions): SvelteComponent
import App({
	target(property) ComponentConstructorOptions<Record<string, any>>.target: Document | Element | ShadowRoot: documentvar document: Documentwindow.document returns a reference to the document contained in the window.
MDN Reference
.querySelector(method) ParentNode.querySelector<Element>(selectors: string): Element | null (+4 overloads)Returns the first element that is a descendant of node that matches selectors.
MDN Reference
('#server-rendered-html'),
	hydrate(property) ComponentConstructorOptions<Record<string, any>>.hydrate?: boolean | undefined: true
});

In Svelte 5+, use mount instead

$set

componentany.$setany(propsany);

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.

componentany.$setany({ answer(property) answer: number: 42 });

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

let propsmodule props
let props: {
    answer: number;
} = $statefunction $state<{
    answer: number;
}>(initial: {
    answer: number;
}): {
    answer: number;
} (+1 overload)
namespace $stateDeclares reactive state.
Example:
let count = $state(0);{@link https://svelte.dev/docs/svelte/$state Documentation}
initial The initial value
({ answer(property) answer: number: 42 });
const componentconst component: any = mountany(Componentany, { props(property) props: {
    answer: number;
} });
// ...
propsmodule props
let props: {
    answer: number;
}.answer(property) answer: number = 24;

$on

componentany.$onany(evany, callbackany);

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 offconst off: any = componentany.$onany('selected', (event(parameter) event: any) => {
	consolenamespace console
var console: ConsoleThe console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to errsource
.log(method) Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
v0.1.100
(event(parameter) event: any.detailany.selectionany);
});

offconst off: any();

In Svelte 5+, pass callback props instead

$destroy

componentany.$destroyany();

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

In Svelte 5+, use unmount instead

Component props

componentany.propany;

componentmodule component.prop(property) component.prop: any = valueany;

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.

consolenamespace console
var console: ConsoleThe console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to errsource
.log(method) Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
v0.1.100
(componentany.countany);
componentany.countany += 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 resultconst result: any = Componentany.renderany(...)

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.

requirevar require: NodeJS.Require
(id: string) => anyUsed to import modules, JSON, and local files.
v0.1.13
('svelte/register');

const Appnamespace App
const App: anyIt's possible to tell SvelteKit how to type objects inside your app by declaring the App namespace. By default, a new project will have a file called src/app.d.ts containing the following:
declare global {
	namespace App {
		// interface Error {}
		// interface Locals {}
		// interface PageData {}
		// interface PageState {}
		// interface Platform {}
	}
}

export {};
The export {} line exists because without it, the file would be treated as an ambient module which prevents you from adding import declarations.
If you need to add ambient declare module declarations, do so in a separate file like src/ambient.d.ts.
By populating these interfaces, you will gain type safety when using event.locals, event.platform, and data from load functions.
 = requirevar require: NodeJS.Require
(id: string) => anyUsed to import modules, JSON, and local files.
v0.1.13
('./App.svelte').defaultany;

const { headconst head: any, htmlconst html: any, cssconst css: any } = Appnamespace App
const App: anyIt's possible to tell SvelteKit how to type objects inside your app by declaring the App namespace. By default, a new project will have a file called src/app.d.ts containing the following:
declare global {
	namespace App {
		// interface Error {}
		// interface Locals {}
		// interface PageData {}
		// interface PageState {}
		// interface Platform {}
	}
}

export {};
The export {} line exists because without it, the file would be treated as an ambient module which prevents you from adding import declarations.
If you need to add ambient declare module declarations, do so in a separate file like src/ambient.d.ts.
By populating these interfaces, you will gain type safety when using event.locals, event.platform, and data from load functions.
.renderany({
	answer(property) answer: number: 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 { headconst head: any, htmlconst html: any, cssconst css: any } = Appany.renderany(
	// props	{ answer(property) answer: number: 42 },
	// options	{
		context(property) context: Map<string, string>: new Mapvar Map: MapConstructor
new <string, string>(iterable?: Iterable<readonly [string, string]> | null | undefined) => Map<string, string> (+3 overloads)([['context-key', 'context-value']])
	}
);

In Svelte 5+, use render instead

Edit this page on GitHub llms.txt

previous next

<svelte:self>