Compiler and API

Client-side component API

Creating a componentpermalink

ts
const component = 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.

ts
import App from './App.svelte';
 
const app = new App({
  target: document.body,
  props: {
    // assuming App.svelte contains something like
    // `export let answer`:
    answer: 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.

ts
import App from './App.svelte';
 
const app = new App({
  target: document.querySelector('#server-rendered-html'),
  hydrate: true
});

$setpermalink

ts
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.

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

$onpermalink

ts
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.

ts
const off = component.$on('selected', (event) => {
  console.log(event.detail.selection);
});
 
off();

$destroypermalink

ts
component.$destroy(options);

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

options may contain the property runOutro which indicates whether to play any outro transitions before the component is destroyed.

Component propspermalink

ts
component.prop;

ts
component.prop = 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.

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

previous svelte/compiler

next Server-side component API