Custom renderers
By default, Svelte components render to the DOM. A custom renderer lets them render to something else instead — a WebGL scene, a native mobile UI, a terminal, a PDF document — while you keep writing ordinary Svelte components with state, props, control flow and everything else you’re used to.
The renderer is a small object that tells Svelte how to create, arrange and update the nodes of the target environment. Svelte takes care of everything else.
This feature is currently experimental, and you must opt in by adding the experimental.customRenderer option wherever you configure Svelte, usually svelte.config.js or vite.config.js:
export default {
compilerOptions: {
experimental: {
customRenderer: true
}
}
};The API may change before the experimental flag is removed.
Choosing a renderer
With the option set to true, components still render to the DOM unless they say otherwise. A component chooses a renderer with <svelte:options>, by pointing to the module that exports it:
<svelte:options customRenderer="three-renderer" />
<script>
let { speed } = $props();
let rotation = $state(0);
</script>
<mesh rotation={[0, rotation, 0]} onclick={() => (rotation += speed)}>
<boxGeometry args={[1, 1, 1]} />
</mesh><svelte:options customRenderer="three-renderer" />
<script lang="ts">
let { speed } = $props();
let rotation = $state(0);
</script>
<mesh rotation={[0, rotation, 0]} onclick={() => (rotation += speed)}>
<boxGeometry args={[1, 1, 1]} />
</mesh>
three-rendereris a made-up package, used as an example throughout this page.
The elements in a custom renderer component — <mesh> and <boxGeometry> here — have no special meaning to Svelte. It passes their names and attributes to the renderer, which decides what to do with them.
The module path is resolved like any other import in the component, so it can be a package name, an alias, or a path relative to the component (customRenderer="./renderer.js").
Setting a default renderer
If most of your components use the same renderer, you can make it the default by passing the module path instead of true:
export default {
compilerOptions: {
experimental: {
customRenderer: 'three-renderer'
}
}
};Individual components can still choose a different renderer, or no custom renderer at all with <svelte:options customRenderer={null} />.
Every component imports the default renderer module, so a globally configured path can’t be relative — it would be resolved relative to each component, rather than relative to your config file. Use a package name, a subpath import like #lib/renderer.js, or an absolute path.
Choosing a renderer by file
For more control, pass a function. It receives the filename of each component, and returns the renderer module for that component, or null for the DOM:
export default {
compilerOptions: {
experimental: {
customRenderer: ({ filename }) => {
return filename.includes('/src/scene/') ? 'three-renderer' : null;
}
}
}
};Since the function knows which file it’s choosing for, it can also return a path relative to that file. A <svelte:options customRenderer={...}> in a component takes precedence over the function.
Running outside the browser
Many renderers target environments that aren’t browsers at all, such as a terminal, a PDF generator, a native runtime or a test runner. In those environments, svelte normally resolves to its server-side implementation, which renders components to HTML strings rather than running them.
To use custom renderers there, add the svelte-custom-renderer resolve condition, which makes svelte resolve to the implementation that runs components. With Node, run your code with --conditions=svelte-custom-renderer. If you’re using a bundler, add svelte-custom-renderer to its list of resolve conditions. If the condition is missing, Svelte throws an error explaining what to do.
Your components still need to be compiled, as with any Svelte app — for example by bundling them with Vite and vite-plugin-svelte.
As an example, here’s a clock that runs in a terminal:
<svelte:options customRenderer="terminal-renderer" />
<script>
let time = $state(new Date());
$effect(() => {
const interval = setInterval(() => (time = new Date()), 1000);
return () => clearInterval(interval);
});
</script>
<box border="round" padding={1}>
<text bold>The time is {time.toLocaleTimeString()}</text>
</box><svelte:options customRenderer="terminal-renderer" />
<script lang="ts">
let time = $state(new Date());
$effect(() => {
const interval = setInterval(() => (time = new Date()), 1000);
return () => clearInterval(interval);
});
</script>
<box border="round" padding={1}>
<text bold>The time is {time.toLocaleTimeString()}</text>
</box>To start it, pass the renderer to mount, along with a target created by that renderer:
import { mount } from 'svelte';
import renderer, { draw } from 'terminal-renderer';
import Clock from './Clock.svelte';
const screen = renderer.createFragment();
mount(Clock, {
target: screen,
renderer
});
// draw `screen` to the terminal, and again whenever it changes
draw(screen);Like
three-renderer,terminal-rendereris made up. A real terminal renderer would redraw the screen whenever Svelte changes it, by calling methods likeinsertandsetText.
Every second, the effect updates time, Svelte updates the text node through the renderer, and the renderer redraws the screen. A PDF renderer would work the same way, except that instead of drawing continuously, you would convert the rendered content to a PDF once mount returns.
props, component exports and unmount work as they do with the DOM.
Using in the browser
In the browser, you can use a custom renderer component inside a regular Svelte app, just like any other component, provided its renderer supports being used inside the DOM. Most renderers designed for the browser will, but check the renderer’s documentation, and see Mixing renderers for how this works:
<script>
import Scene from './Scene.svelte';
</script>
<h1>My scene</h1>
<canvas width="800" height="600">
<Scene speed={0.1} />
</canvas><script lang="ts">
import Scene from './Scene.svelte';
</script>
<h1>My scene</h1>
<canvas width="800" height="600">
<Scene speed={0.1} />
</canvas>You can also render an app entirely with a custom renderer, by passing the renderer to mount along with a target created by that renderer, as in the terminal example above:
import { mount } from 'svelte';
import renderer from 'three-renderer';
import Scene from './Scene.svelte';
const root = renderer.createFragment();
mount(Scene, {
target: root,
renderer,
props: { speed: 0.1 }
});
// `root` now contains the scene's nodesWhat’s supported
Custom renderer components support most of Svelte, including runes, props, snippets, components, context, {#if}, {#each}, {#key} and {#await} blocks, <svelte:boundary>, <svelte:element>, attachments, await expressions, and bind: on components.
Attributes, including class, style, class: and style:, are passed to the renderer as attributes (see Writing a renderer). Event attributes like onclick are passed to the renderer’s addEventListener.
Some features only make sense with the DOM, and cause a compile error in custom renderer components:
bind:on elements- transitions (
transition:,in:andout:) and animations (animate:) - the legacy
on:directive {@html ...}<svelte:head>,<svelte:window>,<svelte:document>and<svelte:body><svelte:options css="injected" />
Styles
Svelte still scopes a custom renderer component’s <style>, adding a class like svelte-xyz123 to the elements it applies to, but it doesn’t inject the styles into the page — whether your renderer can make use of CSS is up to the renderer.
If css: 'injected' is set in your compiler options (as it is in development with some setups), it’s ignored for custom renderer components. Setting <svelte:options css="injected" /> in a custom renderer component is an error.
Server-side rendering
Custom renderer components render nothing during server-side rendering. If custom renderer is used in the browser, the components will be created there, after the page has loaded. The DOM around them is server-rendered and hydrated as usual.
Writing a renderer
A renderer module’s default export is an object created with createRenderer from svelte/renderer. Here’s a complete renderer that renders to plain JavaScript objects, which is a good starting point for experimenting. A real renderer would call into the platform it targets instead — creating native views, scene objects, and so on.
import { createRenderer } from 'svelte/renderer';
export default createRenderer({
createFragment() {
return { type: 'fragment', children: [], parent: null };
},
createElement(name) {
return {
type: 'element',
name,
attributes: {},
listeners: {},
children: [],
parent: null
};
},
createText(data) {
return { type: 'text', data, parent: null };
},
createComment(data) {
return { type: 'comment', data, parent: null };
},
getNodeType(node) {
return node.type;
},
getText(node) {
return node.data;
},
setText(node, text) {
node.data = text;
},
getAttribute(element, name) {
return element.attributes[name] ?? null;
},
setAttribute(element, name, value) {
element.attributes[name] = value;
},
removeAttribute(element, name) {
delete element.attributes[name];
},
hasAttribute(element, name) {
return name in element.attributes;
},
getFirstChild(node) {
return node.children[0] ?? null;
},
getLastChild(node) {
return node.children.at(-1) ?? null;
},
getNextSibling(node) {
const siblings = node.parent?.children ?? [];
return siblings[siblings.indexOf(node) + 1] ?? null;
},
getParent(node) {
return node.parent;
},
insert(parent, node, anchor) {
// inserting a fragment inserts its children, and leaves it empty
const nodes = node.type === 'fragment' ? node.children.splice(0) : [node];
// if necessary, remove the child from its existing parent
for (const child of nodes) this.remove(child);
const index = anchor ? parent.children.indexOf(anchor) : parent.children.length;
parent.children.splice(index, 0, ...nodes);
for (const child of nodes) child.parent = parent;
},
remove(node) {
if (node.parent) {
node.parent.children.splice(node.parent.children.indexOf(node), 1);
node.parent = null;
}
},
addEventListener(element, type, handler) {
(element.listeners[type] ??= new Set()).add(handler);
},
removeEventListener(element, type, handler) {
element.listeners[type]?.delete(handler);
}
});
createRendererreturns its argument unchanged — its purpose is to provide type safety.
The following sections describe what Svelte expects from each method.
Nodes
Svelte works with four kinds of node: fragments, elements, text nodes and comments. They can be whatever kind of object makes sense for your renderer.
createFragment()creates a fragment, a temporary container for several nodes. When a fragment is inserted somewhere, its children are moved there and the fragment is left empty. Fragments are also used as mount targetscreateElement(name)creates an element with the given name, such as'mesh'(you get to choose which elements are available in your render target)createText(data)creates a text nodecreateComment(data)creates a comment. Svelte uses comments as invisible markers, for example to remember where the content of an{#if}block goes, so they don’t need to be displayedgetNodeType(node)returns'fragment','element','text'or'comment'getText(node)returns the text of a text node, or the data of a commentsetText(node, text)changes the text of a text node
The tree
insert(parent, node, anchor)insertsnodeintoparentbeforeanchor, or at the end ifanchorisnull. The node may already be in the tree, in which case it should be movedremove(node)removes a node from its parentgetParent(node),getFirstChild(node),getLastChild(node)andgetNextSibling(node)return the corresponding node, ornull
Attributes
setAttribute(element, name, value)is called for every attribute, with the value as it is in the component — a number, an array, an object, a function and so on — rather than converted to a string. This includes attributes that are properties rather than attributes in the DOM, such asvalueandchecked. Whether your renderer treats them as properties, attributes or something else is up to youremoveAttribute(element, name)is called instead ofsetAttributewhen the value isnullorundefinedgetAttribute(element, name)returns the current value, ornullif the attribute isn’t sethasAttribute(element, name)returns whether the attribute is set. Svelte uses this rather than checking whethergetAttributereturnsnull, so in your renderer an attribute can be set and still have the valuenull
class and style are always passed as strings. Svelte combines the class attribute with any class: directives and scoping class, and the style attribute with any style: directives, and sets the result in one go.
Events
addEventListener(element, type, handler, options)is called for event attributes likeonclick, withoptionsdescribing whether the listener is a capturing (onclickcapture) or passive listener. Callhandlerwhenever the event happens — you can pass it whatever arguments make sense for your renderer, and they’ll be passed on to the event handler in the componentremoveEventListener(element, type, handler, options)removes a listener. Like the DOM, Svelte doesn’t call it when an element is removed: an element and its listeners are expected to be discarded together
Crossings
embed and host are optional, and only needed if your renderer will be combined with the DOM or other renderers. They’re described below.
TypeScript
If you’re writing a renderer in TypeScript, pass the types of your nodes to createRenderer, so that each method’s parameters are typed:
import { createRenderer } from 'svelte/renderer';
const renderer = createRenderer<{
fragment: SceneFragment;
element: SceneObject;
text: SceneText;
comment: SceneMarker;
}>({
// ...
});If you don’t, the node types are inferred from the return types of createFragment, createElement, createText and createComment, as long as those methods come first in the object. Passing them explicitly gives clearer error messages, and works in any order.
The Renderer type is exported from svelte/renderer too, for code that works with renderers, such as a function that wraps one. It takes the same record of node types: Renderer<{ fragment: ...; element: ...; text: ...; comment: ... }>.
Mixing renderers
Components that use different renderers can be nested, as long as the renderers involved anticipate it. A page can contain a 3D scene, and the scene can in turn contain DOM content, such as HTML labels positioned over the 3D objects. Context, props, snippets, error boundaries and reactivity all work across the boundary.
If you’re using a renderer library, its documentation should tell you where its components can be used. The rest of this section is for renderer authors.
The place where content from one renderer appears inside content from another is called a crossing. The outer renderer is the host, and the inner one is the guest. At each crossing, Svelte needs two things:
- a
container, owned by the guest, that the guest’s content is rendered into - optionally, a
nodeowned by the host, that represents the guest’s content in the host’s tree. If there isn’t one, Svelte inserts an empty text node
Renderers provide these through two optional methods, embed and host:
embedis called on the guest. It means “I know how to put my content inside another renderer’s tree”hostis called on the host. It means “I know how to make room for another renderer’s content inside my tree”
Svelte first tries the guest’s embed, then the host’s host. If neither exists, it throws an error. The DOM doesn’t have either method, so in a mixed app it’s always the custom renderer that provides them:
| Situation | Method that is called | Example |
|---|---|---|
| Custom renderer content inside the DOM | the custom renderer's embed |
a WebGL scene in a regular page |
| DOM content inside a custom renderer | the custom renderer's host |
HTML labels floating over a 3D scene |
| Renderer A's content inside renderer B | A's embed, or B's host if A has none |
a chart renderer inside a native app |
In other words: implement embed if your renderer will be used inside DOM apps, which is the case for most renderers. Implement host if DOM content (or another renderer’s content) should be able to appear inside your renderer’s tree.
embed
embed receives the host renderer (null for the DOM), along with the parent and anchor of the position the content is rendered at. Here’s how a canvas renderer might use it to render into a <canvas> element written by the user, or to create its own canvas otherwise:
embed({ host, parent }) {
if (host !== null) {
throw new Error('The canvas renderer can only be used inside the DOM');
}
const canvas = parent instanceof HTMLCanvasElement ? parent : document.createElement('canvas');
const scene = create_scene(canvas);
return {
// only insert a canvas if we created one
node: canvas === parent ? undefined : canvas,
// the scene's root node, which the content is rendered into
container: scene.root,
// called once the content has been removed
destroy: () => scene.dispose()
};
}As in this example, throwing an error is the best way to reject a position your renderer doesn’t support. It’s also how you can express requirements like “only inside a <canvas>”.
host
host is the mirror image. It receives the guest renderer (null for the DOM), and returns a node from your renderer to put in your tree, and a container owned by the guest:
host({ guest }) {
if (guest !== null) {
throw new Error('Only DOM content can be rendered inside a scene');
}
// a scene object that displays a DOM element as an overlay
const overlay = create_overlay();
return {
node: overlay,
container: overlay.element,
destroy: () => overlay.dispose()
};
}Rules for crossings
embedandhostare called once for each crossing, synchronously, when the component (or snippet) is created. Each instance of a component gets its own call.parentmay not be attached to anything yet. If the component is at the top level of its parent’s markup,parentis a fragment that hasn’t been inserted yet, so don’t measure layout or assume the page is connected inside these methods. If the component is directly inside an element, such as the<canvas>above,parentis that element.- Svelte inserts and removes the
nodein the host’s tree, and inserts and removes the content in thecontainer.destroyis called after all of that, so only use it to release your own resources — don’t remove thenodeor the content yourself. - Several crossings can share a container, for example several scenes drawn into the same canvas. Svelte keeps their content in the same order as their nodes in the host tree, including when they’re reordered by a keyed
{#each}block. - DOM event handlers like
onclickwork inside a DOM container, even if the container isn’t part of the page. Events don’t propagate from one renderer to another. - Snippets can be passed between renderers, as long as they were created by a component compiled with
experimental.customRenderer. Snippets created withcreateRawSnippetcan’t be rendered by a custom renderer.
Edit this page on GitHub llms.txt