Toast handbook

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Show brief feedback for actions or status changes, with optional icons, actions, and rich content for success, errors, or reminders.

When to use it

Use Toast for short-lived action feedback through Toaster. Keep notification history and activity feeds in persistent content lists.

• Call toast() to enqueue feedback; Toaster manages the queue. When rendering Toast independently, the page removes it after close.

• as="toast" binds to a host click trigger. Leading/trailing roles add content; parts configures only generated controls. Use inherited singleLine with Text lines={1} for short labels. Internal content gaps stay at least 4 CSS px; rich multiline content retains its layout.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { Toast, Button, Text } from '@snowui-design-system/components';</script> <div style="display: flex; flex-direction: column; align-items: center; gap: var(--gap-4); max-width: 100%;">	<Toast singleLine><Text lines={1}>Draft saved</Text></Toast>	<Toast positive singleLine><Text lines={1}>Changes published</Text></Toast>	<Toast positive={false} singleLine><Text lines={1}>Connection lost</Text></Toast></div>

API

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Configuring Toast generated by Toaster

• Toaster.parts.Toast configures generated Toasts. Toaster.parts.Text configures only labels generated from text strings; it does not configure custom children.

• Toaster owns queue state, position, and dismissal events. Explicit Toast Props override part settings.

SnowUI notification delivery has three public pieces:

Standalone panel Toast explicitly uses GENERIC_SCALE_APPEAR_MOTION for opacity and scale at the former Frame timing instead of inheriting whileAppear={true} fallback. Queued Toaster still uses its position-specific slide, opacity, and scale combination; both appearances are retained.

Feature overview

• Six positions: top, top-left, top-right, bottom, bottom-left, and bottom-right, 16px from the viewport edge; default top.

• Leading/Content/Trailing slots; generated icons can be replaced externally.

• Default variant is a dark pill with blur(var(--size-10)) backdrop blur. Rich variant is a Background/3 glass card using .snowui-quick-action-panel blur.

• Automatically dismiss after four seconds by default; duration: 0 persists.

• Hover pauses the dismissal timer; leaving resumes its remaining duration.

• Toast stacks automatically at each position. Defaults: gap=8, maxVisible=3, scaleStep=0.05, stackOpacityStep=0.2; width hugs content. These settings are configurable.

• One Toast root combines entry, exit, stack shifts, and pushed-out last layer. Lifecycle motion uses transform and opacity; stack shifts and scale use independent CSS translate/scale. Stack opacity multiplies Frame fade. On close, play Disappear before removing the queue entry.

Layout model

Main layout model: composite management layout.

• Toaster mounts a page-level Portal on <body> with six absolutely positioned stack regions. Each slot is an absolute Frame using currentState="Appear" | "Disappear" for lifecycle motion.

• HeroUI-style stack indexing sets CSS translate and z-index: index 0 is frontmost, and deeper items shift inward.

• Only the frontmost Toast is interactive. Deeper layers keep real content but differ by position, scale, and opacity.

• An individual Toast uses a Frame row slot-host layout with Leading, Content, and Trailing.

• The rich variant’s close X is an absolute top-right decoration, outside the three slots.

toast(input) command API

import { toast } from "@snowui-design-system/components"; toast("Done");                                        // String shorthand → equivalent to { text: "Done" }toast({ text: "Done", positive: true });              // Positive state → green CheckCircletoast({ text: "Something Wrong", positive: false });  // Warning state → yellow Warningtoast({ text: "Plain Notice" });                      // No positive value → no generated iconconst id = toast({ text: "Persistent notice", duration: 0 });dismissToast(id);                                     // Dismiss manuallyshowToast("saved-template");                          // Trigger <Toast template id="saved-template">

Related functions:

• dismissToast(id: string): void closes one Toast.

• dismissAllToasts(position?: ToastPosition): void closes all Toasts or those at one position.

• showToast(id: string, overrides?: ToastOptions): string | undefined triggers a registered <Toast template id="...">; overrides may change position, duration, and other runtime options.

<Toaster />

Motion behavior

Motion uses one Toast root:

• Lifecycle whileAppear/whileDisappear controls root transform and --su-motion-opacity. Stack shifts and scale use independent CSS translate/scale, so they do not overwrite the lifecycle transform.

• Stack opacity multiplies lifecycle fade. Layers two and three default to 0.8 and 0.6; exiting reduces the current opacity by 20%.

• Extra offscreen exit distance merges into --snowui-toast-stack-translate-y alongside lifecycle percentage motion, so deep layers can leave the viewport.

• Background, shadow, and backdrop-filter stay on the same root; there is no separate blur plate.

• maxVisible limits visible layers, not queued entries. The old last layer enters pushed-out when a new Toast arrives.

• Hovering any visible Toast at a position pauses the whole group’s dismissal timers. Only the front idle layer reveals the close X; deeper layers do not.

Motion parameters

<Toast /> visual component

Inherits FrameProps except children, and adds:

Since v2.0.0, title, description, and icon Props are removed. Pass text through children; positive selects the generated icon, with no icon when omitted.

Global mount and command trigger

<script>    import { Button, Frame, Text, Toast, Toaster, showToast, toast } from "@snowui-design-system/components";</script> <Toaster /> <Button onclick={() => toast("Done")}>Show Toast</Button><Button onclick={() => toast({ text: "Something Wrong", positive: false })}>    Warning</Button><Button    onclick={() =>        toast({            text: "Saved",            positive: true,            variant: "rich",            position: "top-right",        })    }>    Rich Toast</Button>

Standalone Toast (without toast())

<Toast positive>Done</Toast><Toast positive={false}>Something Wrong</Toast><Toast>Plain Notice</Toast><Toast variant="rich" positive>    <Frame column class="flex-1 min-w-0">        <Text>Saved</Text>        <Text class="text-12 text-black-40">Your changes are synced.</Text>    </Frame></Toast>

Embedded as="toast" mode (v1.1.0)

An embedded Toast triggers on host click without an ID or manual showToast. See ComponentGuidelines §5 for floating components’ three activation modes (specs/maintainers/ComponentGuidelines.md).

<Toaster /> <Button variant="filled">    Save    <Toast as="toast" positive position="top-right">Saved</Toast></Button>

Template declaration and button trigger

<Toaster /> <Toast id="saved-rich-toast" template class="items-start" variant="rich" positive style="width: 15rem;">    <Frame column class="flex-1 min-w-0">        <Text>Text</Text>        <Text class="text-12 text-black-40">Text 2</Text>    </Frame>    <Button as="trailing" variant="gray">Button</Button></Toast> <Button onclick={() => showToast("saved-rich-toast", { position: "top-right" })}>    Add Rich Toast</Button>

Replacing generated icons

<Toast positive>    <Icon as="leading"><Heart /></Icon>    Added to favorites</Toast>

This area is maintained by the user; please obtain permission before AI modification.