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](/docs/kit/configuration) Svelte, usually `svelte.config.js` or `vite.config.js`: ```js // @noErrors /// file: svelte.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 (rotation += speed)}> ``` > [!NOTE] `three-renderer` is a made-up package, used as an example throughout this page. The elements in a custom renderer component — `` and `` 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`: ```js // @noErrors /// file: svelte.config.js export default { compilerOptions: { experimental: { customRenderer: 'three-renderer' } } }; ``` Individual components can still choose a different renderer, or no custom renderer at all with ``. 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: ```js // @noErrors /// file: svelte.config.js 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 `` 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](https://nodejs.org/api/packages.html#conditional-exports), 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 The time is {time.toLocaleTimeString()} ``` To start it, pass the renderer to [`mount`](svelte#mount), along with a target created by that renderer: ```js /// file: main.js // @noErrors 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); ``` > [!NOTE] Like `three-renderer`, `terminal-renderer` is made up. A real terminal renderer would redraw the screen whenever Svelte changes it, by calling methods like `insert` and `setText`. 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`](svelte#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](#Mixing-renderers) for how this works: ```svelte

My scene

``` You can also render an app entirely with a custom renderer, by passing the renderer to [`mount`](svelte#mount) along with a target created by that renderer, as in the [terminal example](#Running-outside-the-browser) above: ```js // @noErrors 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 nodes ``` ## What's supported Custom renderer components support most of Svelte, including runes, props, [snippets](snippet), components, [context](context), [`{#if}`](if), [`{#each}`](each), [`{#key}`](key) and [`{#await}`](await) blocks, [``](svelte-boundary), [``](svelte-element), [attachments](@attach), [`await` expressions](await-expressions), and `bind:` on components. Attributes, including `class`, `style`, `class:` and `style:`, are passed to the renderer as attributes (see [Writing a renderer](#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) (`transition:`, `in:` and `out:`) and [animations](animate) (`animate:`) - the legacy [`on:`](legacy-on) directive - [`{@html ...}`](@html) - [``](svelte-head), [``](svelte-window), [``](svelte-document) and [``](svelte-body) - `` ### Styles Svelte still scopes a custom renderer component's `