Notify
The notification stack: a live region that shows each notification made through useNotify as a
Banner with a countdown bar. Render one near the app root, below a
provideNotify. It positions itself, so it needs no wrapper.
<script> provideNotify({ placement: 'top-end' });</script>
<Notify />- Render one
Notifyregion per app, below aprovideNotify. useNotifyhasinfo,success,warning,danger, andpending. Each returns{ id, dismiss }.- Each item is a
Bannerwith a countdown bar.actionsputs a link or a button in its action row. pendinghas no timer and shows a spinner in the chip.progressdraws a bar along the bottom while it runs.persist: truekeeps a notification until the user dismisses it.updateturns a pending notification into its result.
Toast or notification?
Section titled “Toast or notification?”A notification reports something that happened to the user, such as a failure, a lost connection, or long-running work. It carries a title and may persist. A toast confirms an action the user just took, such as Saved or Copied, and goes away on its own.
Anatomy
Section titled “Anatomy”Notify is the region, and it renders one Banner per notification: title, description, an optional action row, the close button, and the countdown. Everything a notification shows comes from the useNotify call that made it, so the region takes no content.
<script> provideNotify();</script>
<Notify />provideNotify and Notify live in one component, and any component below it calls useNotify. The second argument is an optional description.
Code
<script lang="ts"> import { Notify, provideNotify } from "@viamrobotics/prime-ui";
import BasicActions from "./BasicActions.svelte";
provideNotify();</script>
<div class="not-content"> <BasicActions /> <Notify /></div><script lang="ts"> import { useNotify } from "@viamrobotics/prime-ui";
const notify = useNotify();</script>
<button type="button" class="button" onclick={() => notify.danger("Lost connection", "Retrying in the background.")}> Disconnect</button>Pending
Section titled “Pending”pending shows a spinner and never dismisses itself. progress, a percent from 0 to 100, draws a bar along the bottom, and update moves it. Pass the id to update with a result variant to finish, which starts the countdown in the bar’s place.
Code
<script lang="ts"> import { Notify, provideNotify } from "@viamrobotics/prime-ui";
const notify = provideNotify();
let id = $state<string>(); let progress = $state(0);
const start = () => { progress = 0; id = notify.pending("Publishing module", undefined, { progress }).id; };
const advance = () => { if (id === undefined) return; progress = Math.min(progress + 25, 100); notify.update(id, { progress }); };
const finish = () => { if (id === undefined) return; notify.update(id, { variant: "success", title: "Module published" }); id = undefined; };</script>
<div class="not-content flex gap-2"> <button type="button" class="button" onclick={start} disabled={id !== undefined}>Publish</button> <button type="button" class="button" onclick={advance} disabled={id === undefined}> Advance </button> <button type="button" class="button" onclick={finish} disabled={id === undefined}>Finish</button> <Notify /></div>Persistent
Section titled “Persistent”persist: true keeps the notification until it is dismissed. onDismiss runs once it has gone, however it went.
Code
<script lang="ts"> import { Notify, provideNotify } from "@viamrobotics/prime-ui";
const notify = provideNotify();
let dismissed = $state(0);</script>
<div class="not-content flex items-center gap-3"> <button type="button" class="button" onclick={() => notify.warning("Machine offline", "It stays until you dismiss it.", { persist: true, onDismiss: () => dismissed++, })} > Go offline </button> <span class="text-sm text-subtle-1">Dismissed {dismissed} times</span> <Notify /></div>With details
Section titled “With details”The description is a string or a snippet. A snippet renders whatever markup you give it, such as monospace error output.
Code
<script lang="ts"> import { Notify, provideNotify } from "@viamrobotics/prime-ui";
const notify = provideNotify();</script>
{#snippet details()} <span class="font-mono text-xs">exit status 1: missing config attribute "board"</span>{/snippet}
<div class="not-content"> <button type="button" class="button" onclick={() => notify.danger("Failed to start module", details)} > Start module </button> <Notify /></div>With actions
Section titled “With actions”actions is a snippet rendered in the banner’s action row, for a link to what happened or a retry button. update can change it along with the title, description, and variant.
Code
<script lang="ts"> import { Notify, provideNotify } from "@viamrobotics/prime-ui";
const notify = provideNotify();</script>
{#snippet actions()} <a class="link" href="#deployed">View deployment</a>{/snippet}
<div class="not-content"> <button type="button" class="button" onclick={() => notify.success("Deployed", "Version 1.4.0 is live.", { actions })} > Deploy </button> <Notify /></div>States
Section titled “States”Styling
Section titled “Styling”class lands on the region. Each item is a Banner, so its look follows the Banner classes. The countdown bar fills in the variant’s dark tone.
Each item carries data attributes for styling by state.
| Attribute | Values |
|---|---|
data-state |
open, closed |
data-paused |
Present while the timer is held. |
data-first |
Present on the newest item. |
data-placement |
The provider’s placement. |
Keyboard
Section titled “Keyboard”| Key | Action |
|---|---|
| Tab | Focuses the close button of each notification in turn. |
| Escape | Dismisses the focused notification. |
| Alt + T | Moves focus to the region. |
| Enter / Space | On the close button, dismisses the notification. |
Takes extraClasses }: Props as its props.
useNotify
Section titled “useNotify”useNotify returns the methods below, and provideNotify returns the same object. The variant methods take (title, description?, options?), where description is a string or a snippet and options takes duration, persist, actions, progress, and onDismiss.
| Method | Description |
|---|---|
info(...) |
Shows an info notification and returns { id, dismiss }. |
success(...) |
Shows a success notification. |
warning(...) |
Shows a warning notification. |
danger(...) |
Shows a danger notification. |
pending(...) |
Shows a spinner and no timer, with a progress bar when given one. Resolve it with dismiss or update. |
update(id, changes) |
Changes a visible notification in place. changes takes variant, title, description, actions, and progress. Fields left out keep their value. |
dismiss(id?) |
Dismisses one notification, or every notification without an id. |
provideNotify takes placement (default top-end), duration (default 8000 milliseconds), and max (default 5).