gpuix-svelte v0.6.0
llms.txt

UI toolkit

Orbit, a small deployment dashboard built from the toolkit, in a GPUI window: a sidebar with the Orbit logo, a Pro badge, Overview, Deployments and a selected Settings link, key caps for back and forward and Ada Lovelace's account; the Settings screen with Discard and Save changes buttons, General, Members and a dimmed Billing tab, a Project card with Name, Region and Description fields, a Builds card with two toggles, a checkbox, a Node.js radio group with an info button and a Concurrent builds slider, a Danger zone card with a Delete project button, and a Settings saved toast in the corner.

gpuix-svelte-ui is a set of components written once for both renderers: a native window through gpuix-svelte, and a browser DOM through Vite or SvelteKit. Buttons, fields, choices, menus, dialogs, toasts, a few layout and feedback pieces, a router for the screens of an app, and the theme behind them. The window above is examples/ui-app, a small app built from most of them (npm run demo:ui-app in the repository). Every component has a section of its own below, with a sample that runs live on this page, in the DOM. npm run demo:ui opens the showcase, every component on one screen, in a GPUI window, and npm run demo:ui-dom serves it as a page.

Setup

npm install gpuix-svelte gpuix-svelte-ui
<script>
  import { Button, Card, apply_theme } from 'gpuix-svelte-ui';

  $effect(() => apply_theme('dark'));
</script>

<Card title="Hello">
  <Button variant="primary" onclick={() => console.log('clicked')}>Click me</Button>
</Card>

Every component reads its colours from --ui-* tokens, and apply_theme() puts a palette in force on either renderer: through set_css_vars on GPUI, as custom properties on :root in a browser. Call it from an $effect at the root, before anything paints, so no token is missing on the first frame. The components themselves resolve through the package's own exports, so gpuix-svelte-ui/components/Button.svelte is the same file as Button from the barrel.

In a GPUI app nothing else is needed. A page wants a stylesheet with what a window gives for free: * { box-sizing: border-box }, a font, input, textarea { font: inherit } so the fields take it too, and body { margin: 0 } (render() sets the last one; see packages/ui/showcase/index.html). A prerendered SvelteKit page can carry the palette before any effect runs:

<script>
  import { DARK, theme_rule } from 'gpuix-svelte-ui';
</script>

<svelte:head>
  {@html `<style>${theme_rule(DARK)}</style>`}
</svelte:head>

The components are typed as GPUI markup, so an app that ships to both targets typechecks them with the GPUI project's tsconfig, as DOM explains; svelte-check on a SvelteKit side types them as DOM markup, which they pass too.

Theme

apply_theme(palette) takes 'dark', 'light' or a Palette of your own. DARK and LIGHT are the two it ships, and theme.palette is the one in force, reactive, for the odd place that needs a value in JavaScript (TextField hands GPUI's input a theme object rather than CSS).

Token What it colours
bg, panel, raised, raised-hover the window, cards and dialogs, badges and hovered rows
border, border-strong hairlines and control outlines
ink, muted text
accent, accent-ink, accent-wash, on-accent the brand colour, its legible text, a translucent wash, text on it
success, warning, danger, each with a -wash tones for badges, toasts and progress

Each is a --ui-<token> custom property, so your own markup can read var(--ui-accent) next to the components, and theme_vars(palette) is the full map should you want to set them yourself. The same call sets the tokens gpuix-svelte's own Tooltip, Popover and Scroller read.

The button below switches the palette, and since the tokens are global, every sample on this page follows it.

<script>
  import { Button, Badge, apply_theme, theme } from 'gpuix-svelte-ui';

  let dark = $state(true);
  $effect(() => apply_theme(dark ? 'dark' : 'light'));
</script>

<div class="row">
  <Button onclick={() => (dark = !dark)}>{dark ? 'Light' : 'Dark'} theme</Button>
  <Badge tone="accent">{theme.palette.appearance}</Badge>
  <div class="note">accent is {theme.palette.accent}</div>
</div>

<style>
  .row { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; }
  .note { font-size: 13px; color: var(--ui-muted); }
</style>

Buttons, badges and keys

Button

Button is a focusable box: Enter and Space press it, variant is default, primary, ghost or danger, size is md or sm, and disabled takes it out of the tab order. label names a button whose content is an icon. It spreads onmouseenter / onmouseleave, which is what lets a Tooltip wrap it, and onfocus / onblur, so a tip given {...focus} too shows on keyboard focus.

<script>
  import { Button, Icon, Tooltip } from 'gpuix-svelte-ui';

  let count = $state(0);
</script>

<div class="row">
  <Button>Default</Button>
  <Button variant="primary">Primary</Button>
  <Button variant="ghost">Ghost</Button>
  <Button variant="danger">Danger</Button>
  <Button disabled>Disabled</Button>
</div>
<div class="row">
  <Button size="sm" onclick={() => count++}>Count {count}</Button>
  <Button size="sm" label="Search"><Icon name="search" size={14} /></Button>
  <Tooltip content="A tooltip on a button" side="bottom">
    {#snippet children(hover, focus)}
      <Button {...hover} {...focus} size="sm">Hover me</Button>
    {/snippet}
  </Tooltip>
</div>

<style>
  .row { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-bottom: 10px; }
</style>

Badge

Badge is a short label in a pill, coloured by its tone: neutral (the default), accent, success, warning or danger, the same tones Progress and the toasts take.

<script>
  import { Badge } from 'gpuix-svelte-ui';
</script>

<div class="row">
  <Badge>neutral</Badge>
  <Badge tone="accent">accent</Badge>
  <Badge tone="success">success</Badge>
  <Badge tone="warning">warning</Badge>
  <Badge tone="danger">danger</Badge>
</div>

<style>
  .row { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
</style>

Kbd

Kbd draws its content as a key cap, for a shortcut written into a sentence.

<script>
  import { Kbd } from 'gpuix-svelte-ui';
</script>

<div class="row">
  <Kbd>⌘K</Kbd>
  <div class="note">opens the palette,</div>
  <Kbd>Esc</Kbd>
  <div class="note">closes it and</div>
  <Kbd>Tab</Kbd>
  <div class="note">walks the controls.</div>
</div>

<style>
  .row { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; }
  .note { font-size: 13px; color: var(--ui-muted); }
</style>

Icon

Icon draws one of the toolkit's glyphs by name, or any SVG markup through source, size pixels square in the colour of the text around it. ICONS holds the glyphs by name, as markup.

<script>
  import { ICONS, Icon } from 'gpuix-svelte-ui';

  const STAR = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linejoin="round"><path d="M12 3l2.7 5.6 6.1.9-4.4 4.3 1 6.1L12 17l-5.4 2.9 1-6.1-4.4-4.3 6.1-.9z"/></svg>';
</script>

<div class="row">
  {#each Object.keys(ICONS) as name}
    <div class="cell">
      <Icon {name} size={20} />
      <div class="name">{name}</div>
    </div>
  {/each}
</div>
<div class="row">
  <div class="accent"><Icon source={STAR} size={28} /></div>
  <div class="name">source, in the accent colour around it</div>
</div>

<style>
  .row { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; margin-bottom: 14px; }
  .cell { display: flex; flex-direction: column; align-items: center; gap: 6px; min-width: 88px; }
  .name { font-size: 12px; color: var(--ui-muted); }
  .accent { display: flex; color: var(--ui-accent); }
</style>

Cards, layout and feedback

Card

Card holds a title, a description, an actions snippet at the right of the title, the body and a footer snippet; pad and gap space it out.

<script>
  import { Badge, Button, Card } from 'gpuix-svelte-ui';
</script>

<Card title="Export" description="Three files, about a minute.">
  {#snippet actions()}
    <Badge tone="success">ready</Badge>
  {/snippet}
  <div class="note">The body is whatever the card wraps.</div>
  {#snippet footer()}
    <Button size="sm">Cancel</Button>
    <Button size="sm" variant="primary">Start</Button>
  {/snippet}
</Card>

<style>
  .note { font-size: 13px; color: var(--ui-muted); }
</style>

Stack

Stack is a flex box with its spacing as props (direction, gap, align, justify, wrap, pad, grow), in the names both renderers know (start and end, not flex-start).

<script>
  import { Stack } from 'gpuix-svelte-ui';
</script>

<Stack gap={10}>
  <Stack direction="row" gap={8}>
    <div class="box">one</div>
    <div class="box">two</div>
    <div class="box">three</div>
  </Stack>
  <Stack direction="row" justify="space-between">
    <div class="box">start</div>
    <div class="box">end</div>
  </Stack>
  <Stack direction="row" gap={8}>
    <div class="box">fixed</div>
    <Stack grow={1}><div class="box">grows</div></Stack>
  </Stack>
</Stack>

<style>
  .box { padding: 8px 12px; border-radius: 6px; background-color: var(--ui-raised); font-size: 13px; }
</style>

Separator

Separator is a hairline across, or between the items of a row with direction="vertical", and an optional label sits in the middle of it.

<script>
  import { Separator } from 'gpuix-svelte-ui';
</script>

<div class="column">
  <div class="note">Sign in with a passkey</div>
  <Separator label="or" />
  <div class="note">Sign in with a password</div>
  <Separator />
  <div class="row">
    <div class="note">Help</div>
    <Separator direction="vertical" />
    <div class="note">Privacy</div>
    <Separator direction="vertical" />
    <div class="note">Terms</div>
  </div>
</div>

<style>
  .column { display: flex; flex-direction: column; gap: 12px; }
  .row { display: flex; gap: 12px; }
  .note { font-size: 13px; color: var(--ui-muted); }
</style>

Progress

Progress draws value out of max (100 by default) in a tone, with an optional label and, with show_value, the percentage beside it; size is md or sm.

<script>
  import { Button, Progress } from 'gpuix-svelte-ui';

  let upload = $state(35);
</script>

<div class="column">
  <Progress value={upload} label="Upload" show_value />
  <Progress value={92} tone="danger" label="Disk" show_value size="sm" />
  <Progress value={3} max={4} tone="success" size="sm" />
  <div class="row">
    <Button size="sm" onclick={() => (upload = upload >= 100 ? 0 : Math.min(100, upload + 20))}>Advance</Button>
  </div>
</div>

<style>
  .column { display: flex; flex-direction: column; gap: 14px; }
  .row { display: flex; }
</style>

Spinner

Spinner turns while something loads, size pixels across; label is what a screen reader announces (Loading by default).

<script>
  import { Spinner } from 'gpuix-svelte-ui';
</script>

<div class="row">
  <Spinner size={16} />
  <Spinner />
  <Spinner size={28} label="Fetching files" />
  <div class="note">Fetching three files…</div>
</div>

<style>
  .row { display: flex; align-items: center; gap: 14px; }
  .note { font-size: 13px; color: var(--ui-muted); }
</style>

Skeleton

Skeleton is a pulsing placeholder for content still loading: width in pixels or as CSS text such as 60%, height and radius.

<script>
  import { Avatar, Button, Skeleton, Stack } from 'gpuix-svelte-ui';

  let loaded = $state(false);
</script>

<Stack direction="row" gap={12} align="center">
  {#if loaded}
    <Avatar name="Ada Lovelace" size={40} />
    <Stack gap={4} grow={1}>
      <div>Ada Lovelace</div>
      <div class="note">Wrote the first program, in 1843.</div>
    </Stack>
  {:else}
    <Skeleton width={40} height={40} radius={20} />
    <Stack gap={8} grow={1}>
      <Skeleton width="40%" />
      <Skeleton width="85%" height={12} />
    </Stack>
  {/if}
</Stack>
<div class="row">
  <Button size="sm" onclick={() => (loaded = !loaded)}>{loaded ? 'Unload' : 'Load'}</Button>
</div>

<style>
  .note { font-size: 13px; color: var(--ui-muted); }
  .row { display: flex; margin-top: 14px; }
</style>

Avatar

Avatar shows the image at src (a path, a data: URL or an http(s) URL on GPUI, any image URL in a browser) and the initials of name until it has one, size pixels across.

<script>
  import { Avatar } from 'gpuix-svelte-ui';
</script>

<div class="row">
  <Avatar name="Ada Lovelace" size={24} />
  <Avatar name="Grace Hopper" />
  <Avatar name="Alan Turing" size={40} />
  <Avatar name="Katherine Johnson" size={48} />
</div>

<style>
  .row { display: flex; align-items: center; gap: 10px; }
</style>

Fields

TextField

TextField wraps a real input: value in, onchange(value) on every edit, and onsubmit(value) on Enter. It is controlled, so keep value in your state. label, hint and error go around the box, error also colouring it, and a disabled field takes no focus, click or Enter on either renderer. On GPUI the input is native and draws its text from the palette apply_theme set.

<script>
  import { TextField, toast } from 'gpuix-svelte-ui';

  let name = $state('');
  let email = $state('ada@');
</script>

<div class="column">
  <TextField value={name} onchange={(v) => (name = v)} onsubmit={(v) => toast(`Hello, ${v || 'stranger'}`)} label="Name" placeholder="Your name" hint="Enter shows a toast" />
  <TextField value={email} onchange={(v) => (email = v)} label="Email" error={email.includes('.') ? null : 'Needs a domain, like example.com'} />
  <TextField value="acme" onchange={() => {}} label="Workspace" hint="A disabled field" disabled />
</div>

<style>
  .column { display: flex; flex-direction: column; gap: 12px; max-width: 360px; }
</style>

TextArea

TextArea takes the same props for more than one line, and rows for its height. On GPUI it grows from rows up to max_rows as the text does, and Enter inserts a newline unless onsubmit is set, when Shift+Enter still does.

<script>
  import { TextArea } from 'gpuix-svelte-ui';

  let notes = $state('Met with the team.\nNext: ship the toolkit.');
</script>

<div class="column">
  <TextArea value={notes} onchange={(v) => (notes = v)} label="Notes" placeholder="A few lines" rows={3} max_rows={6} hint="{notes.split('\n').length} lines" />
</div>

<style>
  .column { display: flex; flex-direction: column; max-width: 360px; }
</style>

Select

Select is a trigger and a list in a Popover: options are { value, label, disabled?, description? }, value is the chosen one or null, and arrows, Enter and Escape work on the trigger.

<script>
  import { Select } from 'gpuix-svelte-ui';

  let fruit = $state(null);
  const FRUITS = [
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
    { value: 'cherry', label: 'Cherry', disabled: true },
    { value: 'durian', label: 'Durian', description: 'An acquired taste' }
  ];
</script>

<div class="column">
  <Select options={FRUITS} value={fruit} onchange={(v) => (fruit = v)} label="Fruit" placeholder="Pick one" />
  <div class="note">{fruit ? `Picked ${fruit}.` : 'Nothing picked yet.'}</div>
</div>

<style>
  .column { display: flex; flex-direction: column; gap: 12px; max-width: 360px; }
  .note { font-size: 13px; color: var(--ui-muted); }
</style>

Choices and ranges

Toggle

Toggle is a switch: checked and onchange(checked), with a label beside it, and disabled takes it out of the tab order.

<script>
  import { Toggle } from 'gpuix-svelte-ui';

  let wifi = $state(true);
  let bluetooth = $state(false);
</script>

<div class="column">
  <Toggle checked={wifi} onchange={(v) => (wifi = v)} label="Wi-Fi" />
  <Toggle checked={bluetooth} onchange={(v) => (bluetooth = v)} label="Bluetooth" />
  <Toggle checked={false} onchange={() => {}} label="Airplane mode" disabled />
</div>

<style>
  .column { display: flex; flex-direction: column; gap: 12px; }
</style>

Checkbox

Checkbox takes checked and onchange(checked) too, with a label and a description under it.

<script>
  import { Checkbox } from 'gpuix-svelte-ui';

  let terms = $state(false);
  let news = $state(true);
</script>

<div class="column">
  <Checkbox checked={terms} onchange={(v) => (terms = v)} label="Accept the terms" description="Required before you can continue." />
  <Checkbox checked={news} onchange={(v) => (news = v)} label="Send me the newsletter" />
  <Checkbox checked={false} onchange={() => {}} label="Beta features" description="Not available on this plan." disabled />
</div>

<style>
  .column { display: flex; flex-direction: column; gap: 12px; }
</style>

RadioGroup

RadioGroup picks one of its options ({ value, label, description?, disabled? }): value and onchange(value), a label that names the group to a screen reader, and direction="row" to set the options side by side. The arrow keys move the selection and skip a disabled option.

<script>
  import { RadioGroup } from 'gpuix-svelte-ui';

  let plan = $state('pro');
  let size = $state('m');
</script>

<div class="column">
  <RadioGroup
    options={[
      { value: 'free', label: 'Free', description: 'For trying it out' },
      { value: 'pro', label: 'Pro', description: 'Everything, for one person' },
      { value: 'team', label: 'Team', disabled: true }
    ]}
    value={plan}
    onchange={(v) => (plan = v)}
    label="Plan"
  />
  <RadioGroup options={[{ value: 's', label: 'S' }, { value: 'm', label: 'M' }, { value: 'l', label: 'L' }]} value={size} onchange={(v) => (size = v)} label="Size" direction="row" />
</div>

<style>
  .column { display: flex; flex-direction: column; gap: 18px; }
</style>

Tabs

Tabs is a row of tabs over items of { value, label, disabled? }, with value and onchange(value); the panel under it is yours to render. The arrow keys move between tabs and skip a disabled one, and only the selected tab is a tab stop (the first enabled one while value names none).

<script>
  import { Tabs } from 'gpuix-svelte-ui';

  let tab = $state('overview');
</script>

<Tabs items={[{ value: 'overview', label: 'Overview' }, { value: 'activity', label: 'Activity' }, { value: 'billing', label: 'Billing', disabled: true }]} value={tab} onchange={(v) => (tab = v)} />
<div class="panel">
  {#if tab === 'overview'}
    Three projects, one of them shared.
  {:else}
    Nothing has happened this week.
  {/if}
</div>

<style>
  .panel { padding: 14px 2px 0; font-size: 13px; color: var(--ui-muted); }
</style>

Slider

Slider takes value, min, max, step and onchange(value): drag it, past the window's edge too, click the track, or use the arrows, Home and End. format prints the readout beside its label.

<script>
  import { Slider } from 'gpuix-svelte-ui';

  let volume = $state(40);
  let heat = $state(21);
</script>

<div class="column">
  <Slider value={volume} onchange={(v) => (volume = v)} label="Volume" format={(v) => `${v}%`} />
  <Slider value={heat} onchange={(v) => (heat = v)} min={16} max={28} step={0.5} label="Temperature" format={(v) => `${v.toFixed(1)} °C`} />
</div>

<style>
  .column { display: flex; flex-direction: column; gap: 16px; max-width: 360px; }
</style>

Menu is a Popover with items: { label, onselect, disabled?, danger?, shortcut? }, or { separator: true }. You own open, the trigger toggles it, and an item that runs closes it, as does a press outside or Escape. position opens it at a point instead of beside the trigger, for a context menu.

<script>
  import { Button, Menu } from 'gpuix-svelte-ui';

  let open = $state(false);
  let last = $state('nothing yet');
</script>

<div class="row">
  <Menu
    {open}
    onclose={() => (open = false)}
    items={[
      { label: 'Rename', shortcut: '⌘R', onselect: () => (last = 'Rename') },
      { label: 'Duplicate', shortcut: '⌘D', onselect: () => (last = 'Duplicate') },
      { label: 'Archive', disabled: true },
      { separator: true },
      { label: 'Delete', danger: true, onselect: () => (last = 'Delete') }
    ]}
  >
    <Button onclick={() => (open = !open)}>Actions</Button>
  </Menu>
  <div class="note">Last: {last}</div>
</div>

<style>
  .row { display: flex; align-items: center; gap: 10px; }
  .note { font-size: 13px; color: var(--ui-muted); }
</style>

Dialog

Dialog paints a scrim and a panel in a Portal: open, onclose, title, description, the body and an actions snippet; size is sm, md or lg. Escape, the close button and a click on the scrim call onclose, unless dismissable is false. Escape closes one overlay per press, the one on top: a Select, Menu, Popover or Tooltip open inside a Dialog goes first, and an overlay of your own joins the same stack through dismiss_layer. Neither Dialog nor Menu moves keyboard focus into itself yet, so Tab still walks the controls behind a dialog.

<script>
  import { Button, Dialog, toast } from 'gpuix-svelte-ui';

  let open = $state(false);
</script>

<div class="row">
  <Button variant="danger" onclick={() => (open = true)}>Delete project</Button>
</div>

<Dialog {open} onclose={() => (open = false)} title="Delete this project?" description="This cannot be undone. The files stay on disk.">
  <div class="note">Escape, the close button, Cancel or a click outside closes it.</div>
  {#snippet actions()}
    <Button onclick={() => (open = false)}>Cancel</Button>
    <Button variant="danger" onclick={() => { open = false; toast({ title: 'Project deleted', tone: 'danger' }); }}>Delete</Button>
  {/snippet}
</Dialog>

<style>
  .row { display: flex; }
  .note { font-size: 13px; color: var(--ui-muted); }
</style>

Toaster

toast('Saved') or toast({ title, description, tone, duration, action }) queues a toast from anywhere, and a <Toaster> rendered once, at any position, shows the queue (this page's is the one in the sample below, which shows the other samples' toasts too). A toast goes by itself after duration ms (4000 by default; null keeps it) or when dismissed, and dismiss_toast(id) / clear_toasts() do that from code.

<script>
  import { Button, Toaster, clear_toasts, toast } from 'gpuix-svelte-ui';
</script>

<div class="row">
  <Button size="sm" onclick={() => toast('Saved')}>Toast</Button>
  <Button size="sm" onclick={() => toast({ title: 'Export finished', description: '12 files written.', tone: 'success', action: { label: 'Open', onclick: () => toast('Opened') } })}>With an action</Button>
  <Button size="sm" onclick={() => toast({ title: 'Disk almost full', tone: 'warning', duration: null })}>Sticky</Button>
  <Button size="sm" variant="ghost" onclick={clear_toasts}>Clear</Button>
</div>
<Toaster />

<style>
  .row { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
</style>

Screens and routing

Router

Router switches between screens by path, with a history stack behind it. In a window the stack is in memory, and a hot reload keeps the current screen; in a page the stack is the browser's, so the address bar, back and forward and deep links work (mode="history", the default, or mode="hash" for a static host that cannot rewrite every URL to index.html; mode="memory" leaves the URL alone). A page served below the root, such as /repo/ on GitHub Pages, sets base="/repo": it is stripped before matching and put back on every URL.

The table maps patterns to screens. A :param segment matches one segment, a trailing /* the rest of the path (as params['*'], below any pattern that names those segments), and a bare * whatever nothing else does. Where two patterns fit, the one with a literal at the earliest position where they differ wins, so /items/new beats /items/:id in any order. A screen is a component receiving params and query props, screen(snippet) for an app small enough to keep its screens in one file, or lazy(() => import('./Settings.svelte')) for one imported on its first visit (a failed import is logged and tried again next time).

router.path and router.href are percent-encoded as an address bar has them (/caf%C3%A9), in a window too, so a route reads the same whether it was navigated to, reloaded or gone back to; params holds the decoded values. params['*'] is the remaining segments, each decoded, joined with /, so a segment with an escaped slash in it (a%2Fb) cannot be told from two: a value that may hold a slash belongs in the query. A param that is only . or .. is a param like any other in a window and in hash mode, but a history-mode URL cannot hold such a segment (the browser collapses it), so there the screen shows while the address bar, and a reload, lose it.

A screen mounts fresh when the path changes; a change of query or hidden state alone hands the same screen new props, so a search field that writes ?q= as you type keeps its focus. State that should survive a round trip lives in a module or in that state. A #fragment is the browser's and never part of the route: in history mode a deep link keeps it, navigate('/items#top') puts it in the address bar, and a plain <a href="#section"> on a screen scrolls without navigating.

<script>
  import { Router } from 'gpuix-svelte-ui';
  import Sidebar from './Sidebar.svelte';
  import Home from './Home.svelte';
  import Item from './Item.svelte';
  import NotFound from './NotFound.svelte';
</script>

<Router routes={{ '/': Home, '/items/:id': Item, '*': NotFound }} initial="/">
  {#snippet layout(content, route)}
    <Sidebar current={route.path} />
    {@render content()}
  {/snippet}
</Router>
  • navigate(path, { replace, state }), back() and forward() do the same from code. navigate() returns a promise of whether it arrived: false when a hook cancelled it or a newer navigation overtook it, and a rejection when the history API refuses the entry (a state it cannot clone). With synchronous hooks all of that has happened by the time it returns, so it is awaited only for the answer.
  • A path resolves as a link on the current screen would: edit and ../list from the current path, ?page=2 on it, and an empty path or a bare #fragment stays on the route. A path from the root is taken as written, dots included, which is what keeps a param that is .. a param. A navigation to the URL already shown replaces its entry rather than stacking a second one, while in history mode one to another fragment of it is a new entry, as a fragment link's is, so Back returns to the first.
  • router.path, router.params, router.query, router.state, router.can_go_back and router.can_go_forward are reactive wherever they are read, and router.search is the query as URLSearchParams, for a key that repeats (router.search.getAll('tag')).
  • href('/items/:id', { id: 3 }, { tag: ['a', 'b'] }) builds a path with its params typed from the pattern, plus an optional query whose arrays repeat their key.
  • before((to, from) => …) runs before every navigation (a Link, navigate(), the keyboard, the browser's buttons and the first screen alike): false cancels it, a string redirects it, and a promise of either is waited for, so a hook can ask in a Dialog before leaving unsaved changes. Hooks are asked in order, and router.navigating holds the route while one decides. A newer navigation overtakes one still waiting, whose remaining hooks are not asked. A hook that throws or rejects cancels, a redirect loop gives up after ten hops, both logged, and a hook that calls navigate() itself replaces the navigation it was asked about. Only the route a redirect ends on arrives: the screen redirected away from never shows. It returns the unsubscribe.
  • Back and forward have moved the stack by the time a hook hears of them, in a window as in a browser. While the hook decides, router.can_go_back and router.can_go_forward describe the entry gone to, and a second Back goes one further; a no moves the stack back, and a redirect replaces the entry gone to. Coming back onto the screen still shown (Back, then Forward) asks nothing, and a navigate() made meanwhile starts from the screen shown, which in a page means once the browser is back on its entry.
  • Register hooks before the Router mounts for them to see the first screen. There from is to itself, an async hook is waited for (router.ready is false and the Router renders nothing meanwhile), and a redirect replaces the screen before it shows. Nothing is shown yet to stay on, so false lets the first screen through: a hook that guards a screen redirects.
  • after((to, from) => …) runs once a route has arrived, the first screen included, for a title, analytics or moving focus.
  • In a window, ⌘[ and ⌘] (Alt+Left and Alt+Right elsewhere) go back and forward unless a text field has focus; a page leaves those keys to the browser, which has them already. shortcuts sets either way.

One Router per app: the store behind it is global, which is what lets a Link anywhere, a menu item or a keyboard shortcut navigate without a reference to the router. It is a client-side router for a window and a Vite page; a SvelteKit site has Kit's router for its pages and would use this one only inside a window.

<script>
  import { Badge, Button, Link, Router, back, forward, href, router, screen } from 'gpuix-svelte-ui';
</script>

{#snippet home()}
  <div class="note">Home. Pick a link, then use the buttons.</div>
{/snippet}
{#snippet items()}
  <div class="row">
    <div class="note">Items:</div>
    {#each [1, 2, 3] as id}
      <Link href={href('/items/:id', { id })}><Badge>#{id}</Badge></Link>
    {/each}
  </div>
{/snippet}
{#snippet item({ params })}
  <div class="note">Item {params.id}, with params typed from its pattern.</div>
{/snippet}
{#snippet lost()}
  <div class="note">Nothing at {router.path}.</div>
{/snippet}

<div class="row">
  <Link href="/">{#snippet children({ active })}<Badge tone={active ? 'accent' : 'neutral'}>Home</Badge>{/snippet}</Link>
  <Link href="/items">{#snippet children({ active })}<Badge tone={active ? 'accent' : 'neutral'}>Items</Badge>{/snippet}</Link>
  <Link href="/elsewhere">{#snippet children({ active })}<Badge tone={active ? 'accent' : 'neutral'}>Elsewhere</Badge>{/snippet}</Link>
  <Button size="sm" disabled={!router.can_go_back} onclick={back}>Back</Button>
  <Button size="sm" disabled={!router.can_go_forward} onclick={forward}>Forward</Button>
</div>
<div class="screen">
  <Router routes={{ '/': screen(home), '/items': screen(items), '/items/:id': screen(item), '*': screen(lost) }} mode="memory" shortcuts={false} />
</div>
<div class="note">router.href is {router.href}</div>

<style>
  .row { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
  .screen { display: flex; flex-direction: column; min-height: 40px; margin: 10px 0; padding: 10px 12px; border-radius: 8px; background: var(--ui-raised); }
  .note { font-size: 13px; color: var(--ui-muted); }
</style>

<Link href="/items/3"> navigates on click. It is a real <a> in a page, so a modified click opens a new tab, a click a child handler already prevented is left alone, and an href to another site (https:, mailto:) is followed by the browser; in a window it is a focusable box, which has nothing to open another site with. Its content snippet gets { active }, true on that screen and the ones below it (exact limits it to the path itself, and a query in href has to match too), and a page's active link carries aria-current="page". replace and state go to the navigation. A Link needs no Router near it: these drive the same store as the sample above.

<script>
  import { Badge, Link, router } from 'gpuix-svelte-ui';
</script>

<div class="row">
  {#each [['/', 'Home'], ['/items', 'Items'], ['/items/3', 'Item 3']] as [path, name]}
    <Link href={path}>
      {#snippet children({ active })}<Badge tone={active ? 'accent' : 'neutral'}>{name}</Badge>{/snippet}
    </Link>
  {/each}
</div>
<div class="note">At {router.path}; Items stays active on the screens under it.</div>

<style>
  .row { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-bottom: 10px; }
  .note { font-size: 13px; color: var(--ui-muted); }
</style>

Responsive layouts

Both renderers answer @media queries over the window's width and height (Styling), and media_query() answers the same from JavaScript (Guide). The toolkit adds named breakpoints: BREAKPOINTS is { sm: 480, md: 768, lg: 1024, xl: 1280 }, min_width('md') is media_query('(min-width: 768px)') and max_width('md') is media_query('(width < 768px)'), everything narrower, in the range form that leaves no fractional width between the two. Under md this sample stacks its cards and says so; resize the browser to see both halves agree:

<script>
  import { Badge, Card, max_width } from 'gpuix-svelte-ui';

  const narrow = max_width('md');
</script>

<div class="cards">
  {#each ['One', 'Two', 'Three'] as title}
    <div class="cell"><Card {title}>A card that stacks under 768 px.</Card></div>
  {/each}
</div>
<div class="row">
  <Badge tone={narrow.current ? 'warning' : 'success'}>{narrow.current ? 'stacked' : 'side by side'}</Badge>
</div>

<style>
  .cards { display: flex; flex-direction: row; gap: 12px; }
  .cell { display: flex; flex-direction: column; flex-grow: 1; flex-basis: 0; }
  @media (width < 768px) {
    .cards { flex-direction: column; }
  }
  .row { display: flex; margin-top: 10px; }
</style>

Writing your own

The helpers the components are built on are exported, so a component of your own can be cross-target the same way (see DOM for the rules):

  • own_hitbox spreads hitbox="self" on GPUI and nothing in the DOM, for a clickable box with painted children.
  • test_id(id) spreads testid on GPUI and data-testid in the DOM, which is what every component's testid prop becomes.
  • aria_checked(checked) spreads the state attribute each renderer's accessibility tree reads, and aria_disabled(disabled) the one that tells a page's screen reader a control is off (GPUI has no disabled state to set).
  • key_of(e) spells a key event's key the GPUI way on both renderers (enter, space, up), activates(e) says whether it presses a button, repeats(e) whether the key is held, and chorded(e) whether Alt, Ctrl or Cmd is: the arrow keys of a control leave such a chord to the browser or the app (Alt+Left is Back).
  • bounds_of(node), pointer_x(e) and still_pressed(e) read a box, a pointer and a held button in one coordinate space, for drags. {...drag_handlers(down, move, release)} on the element pressed keeps a drag going past it and the window's edge: mouse handlers on GPUI, which captures the pointer for them, and pointer events with a capture in a page, so a finger drags too (give the element a touch-action). Slider is built on it.
  • focus_node(node) focuses whatever an {@attach} handed over, and holds_focus(node) says whether the keyboard focus is on it or inside it.
  • MONO is a monospace family each side has (var(--ui-mono) in CSS).

Every interactive component takes a testid, and the derived ids are documented on each prop (<testid>-input, <testid>-panel, <testid>-<value>), so a headless test on GPUI (Testing) and a DOM test find the same things: the repository's test/ui.ts and test/ui-dom.ts click through the whole showcase that way.