Toaster handbook

v1.0.3 · @snowui-design-system/components

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

Display global notifications created with toast() in one host. Six screen positions, stacking motion, and a visible-item limit keep successive feedback orderly.

When to use it

Use it as the display host for Toast, coordinating the notification queue and layout. Keep a page’s persistent notification history in the application rather than turning every past message into a transient Toast.

Mount the notification host and create messages with toast(). maxVisible limits how many are shown at once.
Notifications created in one runtime share a queue. Mount one Toaster at the application root and reuse it across page regions; multiple hosts display duplicate copies of the same notification.
offset and gap control position and stacking spacing. parts configures generated Toasts and Text labels for string notifications; explicit appearance on one message takes priority.

Quick start

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

<script lang="ts">	import { Button } from '@snowui-design-system/components';	import { Toaster, toast, dismissAllToasts } from '@snowui-design-system/components';</script> <div style="display: flex; align-items: center; justify-content: center; flex-wrap: wrap; gap: var(--gap-4) var(--gap-3);">	<Button onclick={() => toast({ text: "Changes saved", positive: true })}>Save changes</Button>	<Button onclick={() => toast({ text: "Connection lost", positive: false })}>Connection error</Button></div><Toaster />

API

Keyword	Type	Default	Description
offset	`number`	`16`	Distance from the viewport edge to the Toast region, in px
maxVisible	`number`	`3`	Maximum visible layers per position. This limits visible layers, not the number of messages queued by `toast()`; a new Toast pushes out the last visible layer at the limit.
gap	`number`	`8`	Visual offset between Toasts at the same position, in px
scaleStep	`number`	`0.05`	Scale reduction per stacked layer; the layer at `index=1` scales to `0.95` by default
stackOpacityStep	`number`	`0.2`	Opacity reduction per stacked layer; the second and third layers default to `0.8` and `0.6`
stackMinOpacity	`number`	`0.6`	Minimum opacity for stacked items
stackDuration	`number`	`300`	Duration of stack transition, in ms
stackEasing	`string`	`"ease"`	Easing for stack transition
width	`number \| string`	—	Width of the Toast region. Content determines width by default; a supplied width fixes it. On narrow screens it is capped at `calc(100vw - 2rem)`.
parts	`ComponentPartsOf<{ Toast: typeof Toast; Text: typeof Text }>`	—	Configure generated Toast appearance and Text labels for text strings. Text defaults to lines=1; explicit children do not read parts.Text. Toaster retains queue data, position, and dismissal behavior; explicit notification Props take priority.

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

Built-in component modes

parts.Toast configures all Toasts directly created by Toaster. parts.Text configures only labels generated from text strings, which default to a single line with full-text truncation hints.
Toaster controls Toast queue data, position, close events, and stacking motion; a part cannot override them.
Parts apply only to Toasts and text labels created by Toaster. They do not recurse into Toast internals or configure explicit leading, children, or trailing content.
Explicit Props on a Toast instance take precedence over parts.Toast. Classes merge; styles merge with parts first and the explicit style last.

Examples

<Toaster    parts={{        Toast: {            variant: "rich",            size: "md",        },    }}/>

For the full Toast API, see Toast.

Positioning rules

The top and bottom regions span the available width between the viewport’s left and right offsets. Notifications center within the region at the width set by their content or width.
The region does not depend on absolutely positioned children for intrinsic width. This prevents a notification from growing rightward from the viewport center when an empty region would otherwise have zero width.

Toaster style overrides

Read the full LICENSE first; reuse that review for the same task, version, and scope.

First use public component Props to match the desired appearance, preserving the existing look where possible. If changes are necessary, follow the style selection and override order: use your own class (including Tailwind already in the project) or an instance style. The names below are public overrides actually consumed by source; check their scope and do not modify private DOM. Choose the correct SnowUI token family. External apps need not install SnowUI website utilities.

This component source does not directly consume a registered component-specific override. Style composed children through public parts or an explicit child; do not guess variable names.

Design guide · Tokens · Composition boundaries

Toaster types and states

Required Props: no named required Props.

Bindable Props: this component declares no named two-way binding; handle state updates through public callbacks or its host.

Inherited declaration: none. Consult the relevant base component’s public documentation for any capabilities it exposes; omitted fields cannot be used as if they were inherited.

Shared Frame API · Back to API

The following type declarations are actually referenced by public Props and come from source. A Svelte Snippet denotes a content fragment; ComponentProps denotes the Props of the corresponding component.

ComponentPartsOf

Source: components/src/logic/component-parts.svelte.ts

export type ComponentPartsOf<    T extends Record<string, Component<any>>,> = {    [K in keyof T]?: ConfigurableComponentPartProps<T[K]>;};

ConfigurableComponentPartProps

Source: components/src/logic/component-parts.svelte.ts

export type ConfigurableComponentPartProps<C extends Component<any>> = Partial<    Omit<ComponentProps<C>, ComponentPartControlledKey>>;

ComponentPartControlledKey

Source: components/src/logic/component-parts.svelte.ts

export type ComponentPartControlledKey =    | "children"    | "as"    | "value"    | "defaultValue"    | "open"    | "selected"    | "checked"    | "disabled"    | "readonly"    | "id"    | `on${string}`    | `aria-${string}`;