Playground
One loading indicator in three shapes, and it knows when the page is waiting. sb-busy listens for Datastar's datastar-fetch events and shows itself while a request it watches is in flight, so a button plus an indicator needs no signal, no data-indicator and no server round trip to appear.
Two things decide whether it is up, and they are kept strictly apart:
- The server owns
busy. A long job the server knows about setsbusyon the element, and it wins: the indicator stays up until the server takes the attribute away. Any value counts as busy,busy="false"too, as in HTML. - The component owns the rest locally. Which watched requests are in flight, the
delay/mintimers and the animation state live in$$signals and closure variables, never in attributes: a morph resets attributes, and the indicator must not blink every time the server re-renders the page.
The visible state is busy or a watched request in flight, put through delay and min. Every flip emits sb-busy-change with { busy }.
Examples
The three variants
<div style="display: grid; gap: 24px; inline-size: min(100%, 24rem)">
<sb-busy busy show-label label="Docking"></sb-busy>
<sb-busy busy variant="bar" label="Uploading"></sb-busy>
<sb-busy busy variant="bar" value="64" label="Uploading" show-label></sb-busy>
<sb-busy busy variant="skeleton" lines="3" label="Loading crew"></sb-busy>
</div>
A bar with no value sweeps (indeterminate); with value between 0 and 100 it becomes a determinate role="progressbar". Sizes are sm, md and lg:
<div style="display: flex; align-items: center; gap: 24px">
<sb-busy busy size="sm"></sb-busy>
<sb-busy busy size="md"></sb-busy>
<sb-busy busy size="lg"></sb-busy>
</div>
Server-driven
busy is an ordinary attribute, so anything that can set an attribute can drive it: the server's markup, or a signal on the page.
<div data-signals:_working="false" style="display: flex; align-items: center; gap: 16px">
<sb-toggle label="Long job running" data-bind:_working__prop.checked></sb-toggle>
<sb-busy data-attr:busy="$_working" data-preserve-attr="busy" show-label label="Working"></sb-busy>
</div>
Following a real request
This is the point of the component. The button fires a request at a demo endpoint that answers after 900 ms; the sb-busy next to it shows itself for exactly as long as the request is in flight. Nothing is wired between them: with no for, the indicator watches every request coming from inside its own parent element.
<div data-signals="{_crew: []}" style="display: grid; gap: 16px; justify-items: start">
<div style="display: flex; align-items: center; gap: 16px">
<sb-button data-on:click="@get('/demo/data/children?into=_crew&delay=900')">Load the catalog</sb-button>
<sb-busy label="Loading the catalog" show-label></sb-busy>
</div>
<p style="margin: 0; color: var(--sb-text-2)" data-text="$_crew.length ? $_crew.length + ' galaxies' : 'nothing loaded yet'"></p>
</div>
datastar-fetch is dispatched on the document and reaches every listener, so sb-busy checks event.detail.el when a request starts. Requests from elsewhere on the page leave it alone. From then on the request belongs to the element that fired it, and its end counts even if that element is gone by then: a Delete button whose row the response removes still takes the indicator down.
Which requests to watch
for |
watches |
|---|---|
| empty | any request triggered from inside the host's parent element (the host itself included) |
| a CSS selector | requests whose triggering element matches it, or has an ancestor that does (for="#crew-form" covers every control in that form) |
* |
every request on the page |
<div data-signals="{_a: [], _b: []}" style="display: grid; gap: 16px">
<div id="sb-busy-left" style="display: flex; align-items: center; gap: 16px">
<sb-button variant="outline" data-on:click="@get('/demo/data/children?into=_a&delay=900')">Left request</sb-button>
<span style="color: var(--sb-text-2); font-size: 0.8125rem">watched</span>
</div>
<div style="display: flex; align-items: center; gap: 16px">
<sb-button variant="outline" data-on:click="@get('/demo/data/search?q=star&into=_b&delay=900')">Right request</sb-button>
<span style="color: var(--sb-text-2); font-size: 0.8125rem">ignored</span>
</div>
<sb-busy for="#sb-busy-left" variant="bar" label="Loading the left panel" show-label></sb-busy>
</div>
A skeleton usually stands in for the content it is waiting for, so give it the shape of that content and hide the content while it is up:
<div data-signals="{_moons: []}" style="display: grid; gap: 16px">
<sb-button data-on:click="@get('/demo/data/search?q=moon&into=_moons&delay=1200')">Scan for moons</sb-button>
<sb-busy variant="skeleton" lines="4" label="Scanning"></sb-busy>
<ul data-show="$_moons.length" style="margin: 0; color: var(--sb-text-2)">
<template data-for="m in $_moons"><li data-text="m?.label"></li></template>
</ul>
</div>
A spinner inside the button
The most common loading state there is. For a button, reach for sb-button's own loading prop first: it draws the same eight blinking dots as sb-busy, sized from the button's own text and colour, and it blocks clicks (mouse, Enter or Space) in the capture phase. That is what stops a double submit, and a spinner sitting inside the button cannot do it.
<div data-signals="{_synced: []}" style="display: flex; align-items: center; gap: 16px">
<sb-button
data-indicator:_syncing
data-attr:loading="$_syncing"
data-preserve-attr="loading"
data-on:click="@get('/demo/data/children?into=_synced&delay=900')"
>Sync catalog</sb-button>
<span style="color: var(--sb-text-2); font-size: 0.8125rem" data-text="$_synced.length ? 'synced ' + $_synced.length + ' galaxies' : 'not synced yet'"></span>
</div>
data-indicator sets the signal while that element's request is in flight, and data-preserve-attr keeps the attribute through a server morph. That is one signal, and in exchange the button cannot be clicked twice.
Or with no signal at all. Drop an sb-busy into the button instead and it wires itself: it watches the request the button fires and shows itself for exactly as long as it is in flight.
<div data-signals="{_counted: []}" style="display: flex; align-items: center; gap: 16px">
<sb-button variant="outline" data-on:click="@get('/demo/data/children?into=_counted&delay=900')">
<sb-busy size="sm" label="Counting" style="display: contents; --sb-brand: currentColor"></sb-busy>
Count galaxies
</sb-button>
<span style="color: var(--sb-text-2); font-size: 0.8125rem" data-text="$_counted.length ? 'counted ' + $_counted.length + ' galaxies' : 'not counted yet'"></span>
</div>
Which one: sb-button loading when a click starts a command, because only the button itself can swallow the second click; the composed sb-busy when you want no page state at all, or a shape sb-button does not draw (a bar, a skeleton), or the delay and min timings the button prop deliberately leaves out.
The composed version needs no for: the default rule watches any request from inside the host's parent element, and here that parent is the button it sits in. Point for at the button (for="#save") only when the spinner lives somewhere else on the page. The same wiring works for @post('/cmd/…'): sb-busy watches the element, not the method.
Two details make the composed spinner behave inside a button:
display: contentsso the idle spinner costs nothing. The host is aninline-block, and a zero-width child still takes the button's flexgap, which would leave a blank notch in an idle button forever. Withdisplay: contentsthe host generates no box at all: while idle the button is exactly as wide as a button without it, and when the request starts the spinner and its gap appear and the button grows. Nothing is reserved for a state the button is not in. It arrives at once, undecorated;sb-busy::part(spinner)is there if you want to animate it in.--sb-brand: currentColorso the dots take the button's own text colour instead of the brand purple they would be invisible in on a filled button.
When a plain indicator is enough
sb-busy earns its place when you want the spinner, the bar or the skeleton, with delay and min around them. If all the page needs is a control that shows it is working while a request is in flight, data-indicator already does that on its own, and it is lighter:
<sb-button data-indicator:_saving data-attr:loading="$_saving" data-preserve-attr="loading"
data-on:click="@post('/cmd/save')">Save</sb-button>
data-indicator sets $_saving while that element's request is in flight; the same signal drives data-attr:disabled or a CSS class on anything that has no loading of its own. Reach for sb-busy when the wait needs a shape, a delay, a minimum, or a place of its own.
No flash, no flicker
delay is how long a request may take before anything appears, and min is how long the indicator stays once it did appear. A request that finishes inside delay never shows an indicator at all; one that finishes right after it keeps it up for min. The failure of a watched request skips min and drops the indicator at once.
<div data-signals="{_fast: [], _slow: []}" style="display: grid; gap: 16px; justify-items: start">
<div style="display: flex; align-items: center; gap: 16px">
<sb-button variant="outline" data-on:click="@get('/demo/data/children?into=_fast&delay=100')">100 ms request</sb-button>
<sb-button variant="outline" data-on:click="@get('/demo/data/children?into=_slow&delay=1200')">1200 ms request</sb-button>
</div>
<sb-busy delay="300" min="600" label="Loading" show-label></sb-busy>
</div>
Disabling a form while it waits
sb-busy-change fires on every visible flip, so the page can do more than show the indicator.
<div data-signals="{_busy: false, _found: []}" style="display: grid; gap: 16px; justify-items: start">
<div style="display: flex; align-items: center; gap: 16px">
<sb-button data-attr:disabled="$_busy" data-on:click="@get('/demo/data/search?q=a&into=_found&delay=900')">Search</sb-button>
<sb-busy variant="bar" label="Searching" data-on:sb-busy-change="$_busy = evt.detail.busy" style="inline-size: 12rem"></sb-busy>
</div>
<p style="margin: 0; color: var(--sb-text-2)" data-text="$_busy ? 'searching…' : $_found.length + ' results'"></p>
</div>
An sb-busy removed while it is up emits a last { busy: false }, so whatever the page switched on with it is switched off again. Its own data-on listener still hears it; listeners further up do not, since the element has left the document.
The indicator never shows a result before the server produced one: it only says that the page is waiting. The list, the count and the message come from the server's render.
Text and language
Every text it shows or reads out is a prop with an English default, so a page in another language sets them all. {name} in a text stands for a value it fills in.
label: "Loading", what is announced (and shown withshow-label).- The bar's value is read as a percentage formatted with
Intl.NumberFormatin the element's language: the nearestlangattribute (inside another component, the page's), else the browser's.
Styling
Parts: base (the indicator, shown while it is up), spinner, bar, fill, skeleton and label.
| Token | Used for |
|---|---|
--sb-brand, --sb-brand-light |
the dots, the bar fill and the shimmer |
--sb-surface-inset |
the bar track and the skeleton blocks |
--sb-text-2 |
the label |
--sb-notch |
pixel corners on the bar and the skeleton (0 falls back to a border radius), and stepped motion: at 0 the bar fills, sweeps and shimmers smoothly, and the spinner's blocks are round dots, the lit one leaving a fading trail |
inline-size on the host sizes the bar and the skeleton. The host also carries :state(busy) while the indicator is up. It is a CSS custom state, so a server morph cannot reset it:
form:has(sb-busy:state(busy)) { opacity: 0.6; }
The live visible state is on the element as a read-only visible property; busy stays the server's attribute.
A watched request that was already in flight before the element was upgraded is not counted: the component starts watching when it connects. A morph that moves the element keeps what it counted; an element removed and inserted again starts afresh. Long-lived streams (@get on an SSE endpoint) stay in flight until the stream ends, so point for at elements that make one-shot requests.
Accessibility
- A visually hidden
role="status"region (polite) is always there, and it gets thelabeltext when the wait starts, so "Loading systems" is announced then; it is emptied when the wait ends. A region that only appears with its text already in it is not reliably read out. The visible label (show-label) isaria-hidden, so it is not read twice. sb-busysets noaria-busy. It belongs on the content that is loading, not on the indicator, and on an ancestor of the status region it would hold the announcement back. Set it on your own region fromsb-busy-change(data-attr:aria-busy="$_busy && 'true'"with the form example above) or fromdata-indicator.- A determinate bar is a
role="progressbar"witharia-valuemin,aria-valuemax,aria-valuenowand a percentagearia-valuetext, labelled by the same label. An indeterminate bar has noaria-valuenow, which is how "unknown progress" is expressed. In a right-to-left page the bar fills and sweeps from the right. - The spinner dots and the skeleton lines are
aria-hiddendecoration: the text carries the meaning, never the animation. - With
prefers-reduced-motion: reducenothing spins, sweeps or shimmers. Each variant keeps a static state instead: one lit dot, a dimmed full bar, plain blocks. - In forced colors (Windows High Contrast) the dots and the fill are drawn in
CanvasText, and the bar and the skeleton blocks get an outline: forced colors drop the backgrounds and shadows they are otherwise drawn with.
Installation
Add Datastar with Rocket and the Starbase autoloader once per page, then use the tag: the autoloader imports each component the first time its tag appears, including tags a Datastar morph adds later. The Datastar here is v1.0.5 with Starbase's patches. The components also run on the official v1.0.4 and v1.0.5.
<script type="importmap">
{ "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" } }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/autoloader.js"></script>
<button data-on:click="@post('/save')">Save</button>
<sb-busy label="Saving" show-label></sb-busy>No flash of undefined elements: put class="sb-cloak" on <html> and add .sb-cloak :not(:defined) { visibility: hidden } to your CSS. The autoloader removes the class once the page's components are defined.
Load just this component, pinned to this version: all its modules in one minified file with its integrity hash, so the browser refuses it if a single byte changes.
<script type="importmap">
{
"imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
"integrity": {
"https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV"
}
}
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/busy@0421e2f1a55b/busy.bundle.min.js" integrity="sha384-oiW0wWLNIM10ItXxGGlFMB2oxeKupohVpxkpVsCz0YieXtiGy8une1wHQlra1qXR"></script>
<button data-on:click="@post('/save')">Save</button>
<sb-busy label="Saving" show-label></sb-busy>Or the minified module files (one file, which the browser requests as it finds their imports), each pinned in the import map:
<script type="importmap">
{
"imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
"integrity": {
"https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV",
"https://starbase.zweiundeins.gmbh/c/busy@0421e2f1a55b/busy.min.js": "sha384-O3YJJmJ8qDu18mRdpR0px5K2nh6PA/GwXasthnzCFQzRuloFu2a07frpkogJ9lNR"
}
}
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/busy@0421e2f1a55b/busy.min.js" integrity="sha384-O3YJJmJ8qDu18mRdpR0px5K2nh6PA/GwXasthnzCFQzRuloFu2a07frpkogJ9lNR"></script>
<button data-on:click="@post('/save')">Save</button>
<sb-busy label="Saving" show-label></sb-busy>In production, pin today's whole catalog: its autoloader and an import map with integrity hashes, so the browser refuses any file that changed. This map covers Datastar and this component; importmap.json has the hashes of every component, to merge into yours.
<script type="importmap">
{
"imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
"integrity": {
"https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV",
"https://starbase.zweiundeins.gmbh/c/busy@0421e2f1a55b/busy.bundle.min.js": "sha384-oiW0wWLNIM10ItXxGGlFMB2oxeKupohVpxkpVsCz0YieXtiGy8une1wHQlra1qXR"
}
}
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/@81f24b268adb/autoloader.js" integrity="sha384-bWIhsIq9SpNUiIZyG/lv190MgHA05m8BVYA3LyIoE/pgOF3NUt0437e++4Ht1NcS"></script>
<button data-on:click="@post('/save')">Save</button>
<sb-busy label="Saving" show-label></sb-busy>Components import only datastar and their own files, so copying is enough: save each component's one file (and a file it loads on first use, keeping its folder), and point the import map at your own copy of datastar-rocket.js (the /js/ paths stand for yours).
<sb-busy>busy.bundle.min.jsone file 2.7 kB brotli
<script type="importmap">
{ "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/busy/busy.bundle.min.js"></script>
<button data-on:click="@post('/save')">Save</button>
<sb-busy label="Saving" show-label></sb-busy>Or copy the module files, keeping each component's folder, and load each component's module:
<script type="importmap">
{ "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/busy/busy.min.js"></script>
<button data-on:click="@post('/save')">Save</button>
<sb-busy label="Saving" show-label></sb-busy>In Go, render it with its typed templ wrapper: one field per prop, generated from the component's manifest (the module's README has the type rules). Add the module:
go get github.com/zweiundeins/starbase/templ@latestThen load it, pinned with integrity hashes to the versions the module was generated with, and use it:
// In <head>: the components you list, pinned,
@sb.Imports(sb.ImportsProps{Components: []sb.Tag{sb.TagBusy}})
// or the autoloader, which also loads tags a morph adds later: @sb.Imports(sb.ImportsProps{})
// or, around the content of <body>, the components it renders: @sb.Tracked(sb.ImportsProps{}) { … }
<button data-on:click="@post('/save')">Save</button>
@sb.Busy(sb.BusyProps{Label: "Saving", ShowLabel: true})Size
A page loads this component as one file, its bundle, compressed the way it is served (gzip -9, brotli -11): brotli is what it downloads. Datastar and Rocket are shared by every component and not counted.
| File | Original | gzip | brotli |
|---|---|---|---|
busy.bundle.min.js | 6.9 kB | 3.0 kB | 2.7 kB |
As module files: one request, 2.6 kB minified with brotli
For a page that loads the module files as they are, requesting each one as it finds its import, or bundles them itself. Each file compressed on its own; the minified one is what the page downloads, and the readable source is always there too.
| File | Original | gzip | brotli | minified |
|---|---|---|---|---|
busy.js | 15.1 kB | 5.9 kB | 5.1 kB | 2.6 kB |
API reference
Props
| Attribute | Type | Default | Description |
|---|---|---|---|
busy | boolean | false | The server forces the indicator on. It wins: while the attribute is present the indicator stays up whatever the watched requests do; leave it out to clear it. |
variant | "spinner" | "bar" | "skeleton" | "spinner" | Shape: a spinner, a progress bar or skeleton lines. Set it as an attribute (it also picks the host display). |
value | string | "" | Bar only: 0-100 for a determinate bar. Empty means indeterminate. |
lines | number | 3 | Skeleton only: how many placeholder lines. |
label | string | "Loading" | What is being waited for, e.g. "Loading flight plan". Read out by the status region; visible with show-label. |
show-label | boolean | false | Show the label next to the indicator instead of only reading it out. |
size | "sm" | "md" | "lg" | "md" | Spinner box, bar height and skeleton line height. |
for | string | "" | Which requests to watch: a CSS selector matching the element that triggers them (or one of its ancestors), "*" for every request on the page, empty for any request from inside the host's parent element. |
delay | number | 0 | Milliseconds to wait before showing, so a fast request never flashes. Try 200. |
min | number | 0 | Milliseconds to stay up once shown, so it does not flicker. Try 400. |
Events
| Name | Description |
|---|---|
sb-busy-change | When the visible state flips, after delay and min. detail: { busy }: e.g. to disable a form while it is up. |