Rendering Svelte components in both gpuix-svelte and normal DOM
gpuix-svelte's helpers and built-in components render in the DOM as well as in a GPUI window, so
the same components can be shared between a gpuix-svelte app and a normal Svelte app such as
SvelteKit, without changes to their code. A build that does not set the custom-renderer export
condition gets the DOM versions. IS_GPUIX tells a component which renderer it is on.
This is not the WebAssembly build, which is GPUI itself
painting a canvas in the page. Here the browser lays out and paints real DOM elements, your
<style> blocks apply as CSS, and the GPUI-only parts of the API become their nearest browser
equivalent or do nothing.
Setup
A complete project to copy from is
gpuix-svelte-sveltekit-shared-components-demo:
a SvelteKit site on adapter-static and a GPUI window rendering one component library, with the
typechecks for both sides set up. The short version: install gpuix-svelte next to your app's own
svelte, and use the Svelte plugin as usual:
// vite.config.js
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
export default defineConfig({ plugins: [svelte()] });
That is all. Vite, SvelteKit and every other browser toolchain resolve without the
custom-renderer condition, so import { … } from 'gpuix-svelte' lands on the DOM build and
gpuix-svelte/components/Scroller.svelte on the DOM Scroller. (The desktop side always sets
the condition: the bin, gpuix-svelte/build and the tsconfig a scaffolded app comes with.)
gpuix-svelte/dom names the DOM build outright, for a tool that sets the custom-renderer condition
anyway, such as the tsconfig of an app that ships to both targets.
The DOM Scroller, Portal, Tooltip and Popover are compiled by your app's Svelte, so they
need Svelte 5.29 or later (they use {@attach}). Vite dedupes svelte to your app's copy; the
custom-renderer build nested inside the package is never loaded in a browser.
An entry mounts the component the same way a desktop one does:
import { render } from 'gpuix-svelte';
import App from './App.svelte';
render(App, { title: 'My app' });
render() mounts into document.body and sets the page title. <body> gets the box GPUI gives
its root, a flex row filling the viewport with position: relative and no margin, or rootStyle
in its place, so a root with width: 100%; height: 100% fills the page as it fills the window.
It also gets line-height: 1.618, GPUI's default, so a line of text is as tall on both; a
browser's own default follows the font and is tighter. A font shorthand on an element resets it.
width, height, titlebar, tabNavigation, keyboardFocusDim, debugFrameOverlay and
onEvent are ignored. A second render() replaces the first. render_hot exists only to reject
with a message naming the bin, which is what an entry that lands here by mistake has skipped;
Vite's own hot reload takes its place.
The page itself supplies the little that a GPUI window gives for free and render() does not:
copy the stylesheet from
examples/cross-target/index.html, which is a complete
page.
IS_GPUIX
<script>
import { IS_GPUIX } from 'gpuix-svelte';
</script>
{#if IS_GPUIX}
<div onauxclick={menu}>…</div>
{:else}
<div oncontextmenu={menu}>…</div>
{/if}
It is true on GPUI (a native window or the WebAssembly canvas) and false in the DOM,
decided by which module the build resolved, so it can be read at module level, before anything
is mounted.
This page runs the component below in the DOM, so its badge reads DOM; in a window the same
source reads GPUI. Its theme button calls set_css_vars, which here writes custom properties on
:root, so the area around it follows, and window_size is the viewport:
<script>
import { IS_GPUIX, set_css_vars, window_size } from 'gpuix-svelte';
const DARK = { paper: '#111111', ink: '#ededed', panel: '#1f1f1f' };
const LIGHT = { paper: '#fafafa', ink: '#171717', panel: '#ffffff' };
let dark = $state(true);
$effect(() => set_css_vars(dark ? DARK : LIGHT));
</script>
<div class="row">
<div class="badge">{IS_GPUIX ? 'GPUI' : 'DOM'}</div>
<div>{window_size.width} × {window_size.height}</div>
<div class="btn" onclick={() => (dark = !dark)}>{dark ? 'Light' : 'Dark'} theme</div>
</div>
<style>
.row {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 12px;
padding: 16px;
border-radius: 10px;
background-color: var(--paper);
color: var(--ink);
}
.badge {
padding: 2px 10px;
border-radius: 999px;
font-size: 12px;
font-weight: 600;
background-color: var(--ink);
color: var(--paper);
}
.btn {
padding: 6px 12px;
border-radius: 6px;
cursor: pointer;
user-select: none;
background-color: var(--panel);
}
</style>
What the helpers do in the DOM
Same names, same signatures. Where a helper takes a node, the node an {@attach} hands over here
is the DOM element.
set_css_vars({ token: '#fff' })sets--tokenon:root, sovar(--token)in your styles resolves natively;nullremoves one. It writes<html>'s inline style, which is why a value set this way wins over a:rootrule in a<style>block, on GPUI too (Styling).on_window_key('keydown', handler)listens onwindow. The event is shaped like GPUI's:e.keyis spelled the GPUI way (escape,enter,space,up, lowercase letters, and under Alt or Shift the physical key's letter or digit, so ⌥T istwithalt),e.modifiershasshift,ctrl,altandcmd(the Meta key),e.editingis true while a text input, a textarea or a contenteditable has focus, ande.preventDefault()reaches the browser event.render()'sonKeyDown/onKeyUpgo through it too.on_selection_change(handler)hearsselectionchange;e.valueis the selected text.selected_text()isdocument.getSelection()as text, reactive through the same event, andclear_selection()empties it.is_terminal()is false.dismiss_layer({ onEscape })keeps the same stack, with awindowkeydownlistener added as the first layer opens: a handler on the focused element, or a window one subscribed before that, can still calle.preventDefault()to keep the top layer open, as can a handler on the focused element that callse.stopPropagation(). A held key's repeats are ignored.window_sizeisinnerWidth×innerHeight, reactive through the resize event (no polling).window_insetsreads as zero, since the page already sits inside the browser's insets.media_query('(max-width: 700px)')ismatchMedia, so every query a browser knows works here, including the ones GPUI refuses.@mediablocks in a<style>are plain CSS in the DOM; on GPUI the width, height and orientation ones apply too (Styling), so a shared component can use both.set_window_title(t)setsdocument.title;activate_window()callswindow.focus();toggle_fullscreen()uses the Fullscreen API;minimize_window()andzoom_window()do nothing.focus_element(node),focused_element(),blur(),focus_next(),focus_previous(),focus_next_within(node)andfocus_previous_within(node)use the document's focus and walk the usual tab stops (links, buttons, fields,tabindex).scroll_into_view(node)isscrollIntoView({ block: 'nearest' }).set_image(node, bytes)shows the bytes on an<img>through an object URL (SVG bytes are recognised and typed, since browsers sniff every raster format but that one), andset_image_pixels(node, w, h, pixels, format)draws them to a canvas first (bgrais swapped for you). The newest upload per element wins, as on GPUI.elements_at(x, y)isdocument.elementsFromPoint.prompt_for_paths()resolves tonull: a page cannot learn a file's path.read_native()andget_native()returnnull, as they do when there is no window.register_font()does nothing, because aFontFaceneeds the family name spelled out; use@font-face.set_debug_overlay(),debug_overlay(),debug_overlay_stats()and the rest of the overlay API returnundefined;set_keyboard_focus_dim()does nothing.TextSearchandfind_rangesare the same code.find_rangesworks; thehighlightattribute is GPUI's, so a DOMTextSearchcounts no matches.parse_css_text,build_style,to_gpui_eventandGPUI_EVENTSare the same code too.- The host plumbing (
renderer,set_native,create_root,commit,dispatch, …) is not exported: nothing in a browser can use it.render_hotis exported only to reject with a message naming the bin.
The components in the DOM
Same props, same slots, same CSS variables; testid becomes a data-testid attribute.
- Scroller is a column with
overflow-y: auto, so the browser scrolls it and draws the thumb (coloured by--scroller-thumband--scroller-thumb-hoverthroughscrollbar-color).followkeeps the bottom in view while the content grows.virtualandestimateare accepted and lay out every row: there is no virtual list, only the GPUI list's spacing rules. - Portal moves its layer to the end of
<body>,position: fixedover the whole viewport, so a modal, menu or toast paints on top from wherever it is rendered and its children position against the window. - Tooltip and Popover hang a
position: fixedlayer off<body>, placed beside the trigger (orposition) from measured boxes withside,alignandgap, snapped inside the viewport, and placed again every frame while shown, as GPUI's layers are, so it follows a trigger that moves. The tooltip hasrole="tooltip"and takes no pointer, so a click on it lands on what lies beneath, as on GPUI; the popover closes on amousedownoutside the panel and the trigger, and on Escape.
Writing a component for both
The DOM build makes the imports resolve and the components exist; the component itself has to
stay inside what both renderers draw the same way. The repository's
examples/cross-target is one such component, opened in a window by
npm run demo:cross and served by Vite with npm run demo:dom; test:cross-target and
test:dom click through it on each renderer. The
shared-components demo
is a whole library written this way, typechecked as DOM markup and as GPUI markup.
- Use
divfor boxes and text,display: flexwhere you need it, and<style>blocks with class rules and:hover. Colours asvar(--token), declared in a:rootrule or set with oneset_css_varscall, give both the same theme. Both read the same CSS text, with four differences to keep in mind: GPUI takes a bare number as pixels (gap: 8,--gap: 8,set_css_vars({ gap: 8 })) and the browser does not, so give lengths a unit; GPUI draws a border fromborder-widthandborder-coloralone while the browser also needsborder-style: solid, so write all three;pointer-events: noneis inherited in the DOM and per element on GPUI, so a pass-through wrapper's interactive descendants needpointer-events: autoof their own there; and GPUI's root is a flex row, whichrender()gives<body>too. - Avoid what only one side has, or branch on
IS_GPUIX: thehover=/active=attributes andhitbox="self"(plain attributes in the DOM),onauxclickande.isRightClick(oncontextmenuin the DOM),e.valueon inputs (e.target.valuein the DOM),onlayout/onscrollchange/onfiledrop(DOM events differ),<virtual-list>,<anchored>,<markdown>,<code>and<diff>. - A variable declared on an element (
.card { --pad: 4px; },style="--pad: 4px") or handed to a component as a style prop (<Card --pad="4px" />) reaches the same elements on both: that element, or that component, and everything inside. The one exception is the layer of aTooltip, aPopoveror aPortal. In the DOM it hangs off<body>, where only:rootandset_css_varsreach it, while on GPUI it reads the variables of the place it was written in. So give a layer its variables in:root, or through thestylea tooltip and a popover forward (Styling). - Keep a
<div>around a component given style props wherever its only neighbours are<svg>or<text>elements. Svelte reads a fragment (a component's markup, an{#if}or{#each}block, a snippet) whose own elements are all one of those two as SVG, and wraps the component in an SVG<g>there, inside which a browser paints no HTML. A<text>in such a fragment is an SVG element too and stays blank with or without style props, which is one more reason to write text in adiv. A window draws all of it. - Event handlers that only react, without reading GPUI-specific fields, work as they are.
e.stopPropagation()exists on both: in the DOM it stops a mouse event from bubbling; on GPUI, where mouse events never bubble, it skips the key handlers still to come. {@attach}hands over aShadowNodeon GPUI and anHTMLElementin the DOM. The helpers accept either; your own code can tell them apart withIS_GPUIX.- Type the markup in the GPUI project, whose tsconfig names the
gpuixHTMLnamespace. A DOM project'ssvelte-checktypes every element as a DOM element and would flagtestid,hover=andGpuixEvent, so keep shared components out of itsinclude, or let it check only the app's own files. bind:is still refused by the compiler under the custom renderer, so it is out for a shared component on both sides.
The GPUI renderer also sends set_css_vars restyles, hit testing and focus through native code
that the DOM has no equivalent for, so the two never match pixel for pixel. Fonts, line heights
and scrollbars are the usual differences.