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 />provideToastonce near the app root creates the stack, anduseToastanywhere below it creates toasts.info,success,warning, anddangerset the glyph.warninganddangerannounce as analert, the others as astatus.- Hovering the region or focusing a toast holds its timer.
- Escape dismisses the focused toast.
Toast or notification?
Section titled “Toast or notification?”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.
Anatomy
Section titled “Anatomy”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
<script lang="ts"> import { Toast, provideToast } from "@viamrobotics/prime-ui";
import BasicActions from "./BasicActions.svelte";
provideToast();</script>
<div class="not-content"> <BasicActions /> <Toast /></div><script lang="ts"> import { useToast } from "@viamrobotics/prime-ui";
const toast = useToast();</script>
<button type="button" class="button" onclick={() => toast.success("Saved")}>Save</button>With an action
Section titled “With an action”toast.create takes an action. Its handler runs, then the toast dismisses.
Code
<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>Placement
Section titled “Placement”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
<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>States
Section titled “States”Styling
Section titled “Styling”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. |
Keyboard
Section titled “Keyboard”| Key | Action |
|---|---|
| Tab | Focuses each toast's action and close button in turn. |
| Escape | Dismisses the focused toast. |
| Alt + T | Moves focus to the region. |
| Enter / Space | On the action or close button, activates it. |
Takes extraClasses }: Props as its props.
useToast
Section titled “useToast”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).