Skip to content

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 Notify region per app, below a provideNotify.
  • useNotify has info, success, warning, danger, and pending. Each returns { id, dismiss }.
  • Each item is a Banner with a countdown bar. actions puts a link or a button in its action row.
  • pending has no timer and shows a spinner in the chip. progress draws a bar along the bottom while it runs.
  • persist: true keeps a notification until the user dismisses it.
  • update turns a pending notification into its result.

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.

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
Basic.svelte
<script lang="ts">
import { Notify, provideNotify } from "@viamrobotics/prime-ui";
import BasicActions from "./BasicActions.svelte";
provideNotify();
</script>
<div class="not-content">
<BasicActions />
<Notify />
</div>
BasicActions.svelte
<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 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
Pending.svelte
<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>

persist: true keeps the notification until it is dismissed. onDismiss runs once it has gone, however it went.

Dismissed 0 times
Code
Persistent.svelte
<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>

The description is a string or a snippet. A snippet renders whatever markup you give it, such as monospace error output.

Code
WithDetails.svelte
<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>

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
WithActions.svelte
<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>

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.
KeyAction
TabFocuses the close button of each notification in turn.
EscapeDismisses the focused notification.
Alt + TMoves focus to the region.
Enter / SpaceOn the close button, dismisses the notification.

Takes extraClasses }: Props as its props.

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).