dssoca docs
GitHub repository

Toaster

Toast notification host.

Mount once near the app root; drive it imperatively with the `toast` API. The stack anchors at one of six `position`s, supports swipe-to-dismiss, pause-on-hover, an inline action button, and announces via a live region. This page is the canonical reference for the whole toast API: every `toast.*` method and the `toasts` store.

Demo

live · storybook Open in Storybook

Demo loads from https://dssoca-storybook.vercel.app/. Run pnpm storybook for it to render locally.

Usage

svelte
<script>
  import { Toaster, toast, toasts } from 'dssoca';

  // ── one call per kind ───────────────────────────────────────────
  // Auto-dismiss defaults: success/info 4s · error 7s · loading sticky.
  // Every method returns the toast's numeric id.
  toast.success('saved!');
  toast.info('3 services syncing…');
  toast.error('deploy failed', { timeout: 10_000 }); // or a bare number
  const id = toast.loading('uploading…'); // sticky until updated/dismissed

  // ── action button (action toasts default to sticky) ─────────────
  // Return false from onClick to keep the toast open after the click.
  toast.info('build queued', {
    action: { label: 'view', onClick: () => goto('/builds') },
  });

  // ── promise — sticky loading toast, flips on settle ─────────────
  async function save() {
    await toast.promise(api.save(), {
      loading: 'saving…',
      success: 'saved!',                       // or (value) => string
      error: (e) => `failed: ${e.message}`,    // or a plain string
    });
  }

  // ── the toasts store — inspect + control in flight ──────────────
  toasts.update(id, { kind: 'success', message: 'uploaded!' });
  toasts.pause(id);    // hold the auto-dismiss timer (hover does this)
  toasts.resume(id);   // let it run again
  toasts.dismiss(id);  // remove one (visible or still queued)
  toasts.clear();      // remove everything
  toasts.max = 3;      // visible-stack cap (default 3; overflow queues FIFO)
  toasts.items;        // reactive array of the visible toasts
</script>

<Toaster position="bottom-right" />
<button onclick={save}>save</button>

Imperative API (`import { toast } from 'dssoca'`): `toast.success/error/info/loading(msg, opts?)` push a toast and return its id; `opts` is `{ timeout?, action? }` or a bare timeout number. Timeout defaults per kind: success/info 4000ms, error 7000ms, loading 0 (sticky); a timeout <= 0 (or non-finite) means sticky, and a toast carrying an `action` defaults to sticky so the button stays reachable. `action` is `{ label, onClick }` — return `false` from `onClick` to keep the toast open. `toast.promise(p, { loading, success, error })` pushes a sticky loading toast, updates it to success/error when `p` settles (message values may be strings or functions of the value/error), and returns the same promise for chaining. The reactive store is `toasts`: `toasts.items` (visible stack), `toasts.max` (cap, default 3 — overflow queues FIFO and is promoted on dismiss), `toasts.update(id, patch)` (patch `kind`/`message`/`timeout`/`action`; changing `kind` without `timeout` re-applies that kind's default and restarts the timer), `toasts.pause(id)`/`toasts.resume(id)` (what hover does), `toasts.dismiss(id)`, `toasts.clear()`. Exported types: `Toast`, `ToastKind`, `ToastAction`, `ToastOptions`, `ToastPatch`, `PromiseMessages`.

Props

PropTypeDefaultDescription
position'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center''top-right'Where the stack anchors on screen.
size'sm' | 'md' | 'lg'Per-instance size override; inherits the ancestor `data-size-variant` when unset.