Toast

A toast region the server fills, stacks and announces.

zweiundeins <sb-toast> notification snackbar feedback live-region Since 2026-09-23 MIT licence 4.0 kB0 Open in playground Edit on GitHub

Playground

The feedback channel for a CQRS app. The server renders what happened as a list of toasts; the region stacks them in a corner, announces them to assistive technology and dismisses them again on its own. Nothing is invented in the browser: the toasts are server state, and a morph brings the current list.

What belongs where

  • The server owns the list. toasts is the whole truth about which messages exist. Add one in a command, render the page again, and it appears. Drop it and it is gone, everywhere, in every tab.
  • The viewer owns the reading. Which toasts this viewer has already closed, the countdowns, the pause while the pointer or the keyboard is inside, the entrance and exit animations: all local, in $$ signals and plain closure state, never written back to an attribute. A morph therefore never resurrects a toast that was just closed, and never resets a countdown.
  • No pending, no optimistic updates. A toast is the server's confirmation. It has no confirm attribute, no :state(pending) and no revert(), because nothing here is an edit waiting to be accepted.

Closing a toast is view state, so it emits sb-dismiss and hides the toast at once. The server may listen and drop the toast from its list with a command. When an id disappears from toasts, the region forgets it completely, so a later toast that reuses the id is shown again.

Examples

Stacking, announcing, counting down

Local signals stand in for the server here, which is all a docs page needs. A real page hands toasts the list the server rendered.

Info Success Warning Danger
<div data-signals="{_n: 0, _list: []}">
  <div style="display: flex; flex-wrap: wrap; gap: 8px; margin-block-end: 12px">
    <sb-button size="sm" data-on:click="$_n++; $_list = [...$_list, {id: 'i' + $_n, text: 'Telemetry packet ' + $_n + ' received.'}]">Info</sb-button>
    <sb-button size="sm" variant="outline" data-on:click="$_n++; $_list = [...$_list, {id: 'i' + $_n, variant: 'ok', title: 'Saved', text: 'Mission plan stored.'}]">Success</sb-button>
    <sb-button size="sm" variant="outline" data-on:click="$_n++; $_list = [...$_list, {id: 'i' + $_n, variant: 'warn', text: 'Fuel at 18%.'}]">Warning</sb-button>
    <sb-button size="sm" variant="outline" data-on:click="$_n++; $_list = [...$_list, {id: 'i' + $_n, variant: 'danger', title: 'Hull breach', text: 'Seal deck 7 immediately.', duration: 0}]">Danger</sb-button>
  </div>
  <sb-toast
    placement="inline"
    max="3"
    duration="6000"
    data-attr:toasts="JSON.stringify($_list)"
    data-preserve-attr="toasts"
    data-on:sb-dismiss="$_list = $_list.filter(t => t.id !== evt.detail.id)"
  ></sb-toast>
</div>

Hover a toast, or tab into its dismiss button, and every countdown stops until you leave. The danger toast carries duration: 0, so it waits for a human. A dismissed toast fades out even though the page drops it from the list at once.

In a corner

placement pins the stack to one of the six corners of the viewport; inline (used in these docs) puts it in the page flow instead. The newest toast always sits closest to the edge the region is pinned to, and the DOM order follows the visual order, so Tab and screen readers move the way the eye does.

Send a command
<div data-signals="{_m: 0, _corner: []}">
  <sb-button data-on:click="$_m++; $_corner = [...$_corner, {id: 'c' + $_m, variant: 'ok', title: 'Command accepted', text: 'Burn scheduled for T-minus 40.'}]">Send a command</sb-button>
  <sb-toast
    placement="bottom-end"
    label="Mission notifications"
    data-attr:toasts="JSON.stringify($_corner)"
    data-preserve-attr="toasts"
    data-on:sb-dismiss="$_corner = $_corner.filter(t => t.id !== evt.detail.id)"
  ></sb-toast>
</div>

With commands

In a CQRS app nothing about a toast is decided in the browser. A command runs, the page renders again, and the server's render contains the toast:

<sb-toast placement="top-end" max="4" duration="6000"
  toasts='[{"id":"7f2","variant":"ok","title":"Saved","text":"Mission plan stored."}]'
  data-on:sb-dismiss="@post('/cmd/toast-seen', {payload: {tabid: $tabid, ...evt.detail}})"></sb-toast>

The command that produced the message queues it for this session (in tab_state, say, next to the other server-owned UI state); the page renders the queue into toasts. sb-dismiss posts the id back, the command drops it from the queue, and the next render no longer contains it. The region does not wait for that round trip: the toast is hidden the moment it is dismissed, and the server's answer only has to agree.

A toast can carry one control: a link (href) or a button (action), with the page's own words for it in label. A news toast opens what it is about:

<sb-toast placement="top-end" duration="8000" label="Mitteilungen" dismiss-label="Schliessen: {message}"
  toasts='[{"id":"m42","variant":"ok","title":"Das Treffen steht","text":"Samstag, 14 Uhr, mit Anna.","href":"/matches/42","label":"Treffen öffnen"}]'
  data-on:sb-dismiss="@post('/cmd/toast-seen', {payload: {tabid: $tabid, ...evt.detail}})"></sb-toast>

An action asks the server to do something, and the toast closes once it is sent:

<sb-toast placement="top-end" label="Mitteilungen"
  toasts='[{"id":"n7","title":"Neue Nachricht","text":"Anna: Passt dir 14 Uhr?","action":"reply","label":"Antworten"}]'
  data-on:sb-toast-action="@post('/cmd/toast-action', {payload: {tabid: $tabid, ...evt.detail}})"
  data-on:sb-dismiss="@post('/cmd/toast-seen', {payload: {tabid: $tabid, ...evt.detail}})"></sb-toast>

sb-toast-action carries {id, action}; the sb-dismiss that follows it (reason "user") lets the server drop the toast as for any other close.

News with a link Message with an action

<div data-signals="{_k: 0, _news: [], _did: ''}">
  <div style="display: flex; flex-wrap: wrap; gap: 8px; margin-block-end: 12px">
    <sb-button size="sm" data-on:click="$_k++; $_news = [...$_news, {id: 'n' + $_k, variant: 'ok', title: 'Docking slot confirmed', text: 'Bay 4 at 14:00.', href: '#bay-4', label: 'Open the docking plan'}]">News with a link</sb-button>
    <sb-button size="sm" variant="outline" data-on:click="$_k++; $_news = [...$_news, {id: 'n' + $_k, title: 'New message', text: 'Ground: hold at waypoint 3?', action: 'reply', label: 'Reply'}]">Message with an action</sb-button>
  </div>
  <sb-toast
    placement="inline"
    duration="10000"
    data-attr:toasts="JSON.stringify($_news)"
    data-preserve-attr="toasts"
    data-on:sb-toast-action="$_did = evt.detail.action + ' on ' + evt.detail.id"
    data-on:sb-dismiss="$_news = $_news.filter(t => t.id !== evt.detail.id)"
  ></sb-toast>
  <p data-show="$_did" data-text="'sb-toast-action: ' + $_did"></p>
</div>

If the page drives toasts from a signal instead of rendering the attribute, add data-preserve-attr="toasts", or the next morph resets the attribute to the server's markup:

<sb-toast data-attr:toasts="JSON.stringify($messages)" data-preserve-attr="toasts"></sb-toast>

Toasts

Each entry of toasts is {id, title?, text, variant?, duration?, href?, action?, label?}:

  • id: stable and unique in the list. It is the only thing that ties a dismissal to a toast, so reuse it for the same message and never for a different one. Without an id, the message is the id ("Title. Text", or just the text), with #2, #3… for repeats of the same message. Repeats can't be told apart that way: once the first is dismissed and dropped, the next one takes over its id and goes with it, so give repeated messages ids.
  • title: an optional bold first line, in the tone colour.
  • text: the message. A plain string in the array is read as {text}, so its id is the string itself.
  • variant: info (the default), ok, warn or danger. It sets the tone colour and how the message is announced.
  • duration: ms for this toast, overriding the duration prop. 0 makes it sticky.
  • href: a link under the message, label its text. A plain click (or Enter) follows it and closes the toast, with sb-dismiss; a click that opens it elsewhere (Ctrl, Cmd, Shift, Alt or the middle button) keeps the toast. A javascript: URL is not shown.
  • action: a name. The toast gets a button with label as its text; activating it emits sb-toast-action with {id, action} and closes the toast, with sb-dismiss. With both href and action, the toast has the link.
  • label: the text of the link or button. There is no built-in one: without a label, href and action are ignored.

Only the newest max toasts are rendered, and only rendered toasts count down. Older ones wait, and take their turn when a newer one goes, unless the server has dropped them by then.

Events

  • sb-dismiss: {id, reason: "user" | "timeout"}, after a toast went away (its close button, its link or action, dismiss(), clear(), or its countdown).
  • sb-toast-action: {id, action}, when a toast's action button is activated, just before the toast closes.

Methods

  • dismiss(id): dismiss one toast, exactly as the button does (including sb-dismiss).
  • clear(): dismiss every toast, including those waiting behind max (each one emits sb-dismiss).

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: "Notifications", the name of the region.
  • dismiss-label: "Dismiss: {message}", the name of each toast's close button; {message} is the toast's title and text.

A toast's own texts, the link's or action's label included, come with the toast and are never replaced.

Styling

Every part is styleable from the page: ::part(region), ::part(toast), ::part(title), ::part(text), ::part(action) (the link or action button), ::part(close) and ::part(bar) (the remaining-time bar). Tones come from --sb-info, --sb-ok, --sb-warn and --sb-danger, the surface from --sb-surface-raised, and the stack sits at --sb-z-toast. Two component variables tune the geometry:

  • --sb-toast-width: width of the stack (default 22rem; it never exceeds the viewport).
  • --sb-shadow-overlay: the toasts' drop shadow, one shadow without spread, such as 0 8px 16px rgb(0 0 0 / 0.3), or none.
  • --sb-toast-inset: distance from the edges (default 1rem).

Corners and the status light notch with --sb-notch, so the 8-bit look can be turned off per theme (the light is a dot at 0). For prefers-reduced-motion: reduce the entrance and exit animations are dropped, and the bar jumps down in fifths rather than slides.

Accessibility

  • Announcing is separate from the visible stack. The stack moves, fades and reorders, which a live region would read out again and again. So the toasts sit in a plain role="region" with label as its accessible name, and two visually hidden live regions do the announcing: a polite role="status" for info and ok, an assertive role="alert" for warn and danger. An urgent message interrupts, an ordinary one waits for a pause.
  • Focus is never stolen. Nothing is focused when a toast appears. Each toast has a dismiss button named after its message ("Dismiss: Saved. Mission plan stored."), reachable with Tab in the order the toasts are shown. Keyboard focus stays with its toast while the stack changes. When that toast goes, focus moves to its neighbour, and after the last one back to where it came from (unless that was inside another component's shadow root, which the browser does not reveal).
  • Links and actions are real controls. A toast's link is an <a href> and its action a <button>, after the message and before the close button in the tab order. Each is named by its label and described by the toast's title and text (aria-describedby), so it reads as "Treffen öffnen, link, Das Treffen steht Samstag, 14 Uhr" in focus. The live region reads the label after the message, so a listener knows the toast has something to open before tabbing to it. When the link or action closes its toast, keyboard focus moves on like after a dismissal, to the same kind of control in the next toast if it has one.
  • Time can be stopped. Every countdown pauses while the pointer is over the region or the keyboard focus is inside it, so a toast cannot vanish while it is being read or its button is being aimed at. (A button focused by a mouse click does not pause anything, or dismissing one toast would stop all the others.) A toast that must not disappear at all gets duration: 0; one with a link or action that matters may want a longer duration.
  • A hidden page waits. While the page is hidden (document.visibilityState is "hidden": a background tab, a minimised window), every countdown stands still, and it resumes when the page is shown again, so a toast never expires unseen.
  • The countdown is decoration. The bar is aria-hidden; it never carries information that is not in the text.

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>

<sb-toast toasts='[{"id":"saved","variant":"ok","title":"Saved","text":"Your changes are live."}]'></sb-toast>

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/toast@936b34a2cccc/toast.bundle.min.js" integrity="sha384-+74TkQKw84wfBsAM+JH4dRsbIpMy5I78j6GA4/emJAbXG0KAIl29EMj9M7V+TDgO"></script>

<sb-toast toasts='[{"id":"saved","variant":"ok","title":"Saved","text":"Your changes are live."}]'></sb-toast>

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/toast@936b34a2cccc/toast.min.js": "sha384-uxeducHOBNbhB17m3uz9Ic3tC8vXgaGlXjgx+wFoFXj+mAWHXg9dcZaAMGa4iSQD"
    }
  }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/toast@936b34a2cccc/toast.min.js" integrity="sha384-uxeducHOBNbhB17m3uz9Ic3tC8vXgaGlXjgx+wFoFXj+mAWHXg9dcZaAMGa4iSQD"></script>

<sb-toast toasts='[{"id":"saved","variant":"ok","title":"Saved","text":"Your changes are live."}]'></sb-toast>

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/toast@936b34a2cccc/toast.bundle.min.js": "sha384-+74TkQKw84wfBsAM+JH4dRsbIpMy5I78j6GA4/emJAbXG0KAIl29EMj9M7V+TDgO"
    }
  }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/@81f24b268adb/autoloader.js" integrity="sha384-bWIhsIq9SpNUiIZyG/lv190MgHA05m8BVYA3LyIoE/pgOF3NUt0437e++4Ht1NcS"></script>

<sb-toast toasts='[{"id":"saved","variant":"ok","title":"Saved","text":"Your changes are live."}]'></sb-toast>

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-toast>
    • toast.bundle.min.js one file 4.0 kB brotli
<script type="importmap">
  { "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/toast/toast.bundle.min.js"></script>

<sb-toast toasts='[{"id":"saved","variant":"ok","title":"Saved","text":"Your changes are live."}]'></sb-toast>

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/toast/toast.min.js"></script>

<sb-toast toasts='[{"id":"saved","variant":"ok","title":"Saved","text":"Your changes are live."}]'></sb-toast>

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@latest

Then 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.TagToast}})
// 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{}) { … }

@sb.Toast(sb.ToastProps{Toasts: []sb.ToastMessage{{ID: "saved", Title: "Saved", Text: "Your changes are live.", Variant: sb.ToastVariantOK}}})

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.

FileOriginalgzipbrotli
toast.bundle.min.js 10.4 kB4.4 kB4.0 kB
As module files: one request, 3.9 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.

FileOriginalgzipbrotliminified
toast.js 21.1 kB8.0 kB7.0 kB3.9 kB

API reference

Props

AttributeTypeDefaultDescription
toastsjson[]The toasts, oldest first: [{id, title?, text, variant?: info|ok|warn|danger, duration?, href?, action?, label?}]. href (a link) or action (a button that emits sb-toast-action) shows label as a control in the toast; without a label neither is shown. Server state: every morph brings the current list, and a toast the server drops is gone.
placement"top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end" | "inline""bottom-end"Corner of the viewport the stack is pinned to. "inline" puts it in the page flow instead (docs, demos, panels).
maxnumber3How many toasts are shown at once. Older ones wait and appear as newer ones go; only shown toasts count down.
durationnumber5000Default time before a toast dismisses itself, in ms. 0 makes them sticky; a toast may carry its own duration.
labelstring"Notifications"Accessible name of the region.
dismiss-labelstring"Dismiss: {message}"Accessible name of a toast's close button: {message} becomes the toast's title and text.

Events

NameDescription
sb-dismissA toast went away. detail: { id, reason: "user" | "timeout" }. It is already hidden locally; post a command if the server should drop it too.
sb-toast-actionA toast's action button was activated. detail: { id, action }. The toast then closes like a dismissal (sb-dismiss, reason "user").