Skip to content

Toast

The region that shows the toasts a provideToast stack creates. Render one near the app root, below the provideToast call. It is a labeled region fixed to the viewport at the provider’s placement, and each toast inside it announces itself as a status, or as an alert for warning and danger. Hovering the region or focusing a toast holds every timer.

<script lang="ts">
import { Toast, provideToast } from '@viamrobotics/prime-ui';
provideToast({ placement: 'bottom-end' });
</script>
<Toast />
  • provideToast once near the app root creates the stack, and useToast anywhere below it creates toasts.
  • info, success, warning, and danger set the glyph. warning and danger announce as an alert, the others as a status.
  • Hovering the region or focusing a toast holds its timer.
  • Escape dismisses the focused toast.

A toast confirms an action the user just took, such as Saved or Copied. It is one short line and it goes away on its own. Something that happened to the user, such as a failure, a lost connection, or long-running work, belongs in a notification, which carries a title and may persist.

Toast is the region, and it renders one row per toast: the variant glyph, the title, an optional description and action, and the close button. A toast is one short line, so everything it shows comes from the useToast call that made it.

<script>
provideToast();
</script>
<Toast />

provideToast and Toast live in one component, and any component below it calls useToast. The provider has to sit above the consumer, so the two halves are separate files.

Code
Basic.svelte
<script lang="ts">
import { Toast, provideToast } from "@viamrobotics/prime-ui";
import BasicActions from "./BasicActions.svelte";
provideToast();
</script>
<div class="not-content">
<BasicActions />
<Toast />
</div>
BasicActions.svelte
<script lang="ts">
import { useToast } from "@viamrobotics/prime-ui";
const toast = useToast();
</script>
<button type="button" class="button" onclick={() => toast.success("Saved")}>Save</button>

toast.create takes an action. Its handler runs, then the toast dismisses.

Code
WithAction.svelte
<script lang="ts">
import { Toast, provideToast } from "@viamrobotics/prime-ui";
const toast = provideToast();
const remove = () => {
toast.create({
title: "Deleted report.csv",
action: { label: "Undo", onclick: () => toast.success("Restored") },
});
};
</script>
<div class="not-content">
<button type="button" class="button" onclick={remove}>Delete</button>
<Toast />
</div>

provideToast takes a placement, which defaults to bottom. The duration and max options set how long a toast stays and how many show at once.

Code
Placement.svelte
<script lang="ts">
import { Toast, provideToast } from "@viamrobotics/prime-ui";
const toast = provideToast({ placement: "top-end" });
</script>
<div class="not-content">
<button type="button" class="button" onclick={() => toast.info("Copied")}>Copy</button>
<Toast />
</div>

class lands on the region. The row’s look is fixed.

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 each toast's action and close button in turn.
EscapeDismisses the focused toast.
Alt + TMoves focus to the region.
Enter / SpaceOn the action or close button, activates it.

Takes extraClasses }: Props as its props.

useToast returns the methods below, and provideToast returns the same object. Every method that takes an id accepts the one create returned.

Method Description
create(options) Shows a toast and returns its id. Takes title, description, variant, duration, and action.
info(title, options?) create with the info variant.
success(title, options?) create with the success variant.
warning(title, options?) create with the warning variant.
danger(title, options?) create with the danger variant.
update(id, options) Changes a visible toast in place.
dismiss(id?) Dismisses one toast, or every toast without an id.
pause(id?) Holds one toast’s timer, or every timer without an id.
resume(id?) Restarts a timer pause held.

provideToast takes placement (default bottom), duration (default 4000 milliseconds), and max (default 3).