gooey-toast

gooey-toast

A framework-agnostic, physics-inspired toast notification package.

Inspired by the original React Sileo project by Aryan Arora, this package brings the same gooey toast feel to framework-agnostic apps.

Live demo: janusfil.github.io/gooey-toast

• No React/Vue peer dependency
• Works in Vue, React, Svelte, Astro, vanilla JS, and more
• Keeps the gooey SVG + spring motion style
• Optional visual timeout bar for auto-dismiss toasts

Installation

npm i gooey-toast

Or install a downloaded release tarball locally:

npm i ./path/to/gooey-toast-<version>.tgz

Quick start (vanilla JS/TS)

import { mountToaster, toast } from "gooey-toast";
import "gooey-toast/styles.css";

mountToaster({
  position: "top-right",
});

toast.success({
  title: "Saved",
  description: "Your settings have been updated.",
});

toast.* also auto-mounts a default toaster in document.body if you do not call mountToaster yourself.

Vue usage

// main.ts
import { createApp } from "vue";
import App from "./App.vue";
import { mountToaster } from "gooey-toast";
import "gooey-toast/styles.css";

mountToaster({ position: "top-right" });

createApp(App).mount("#app");

<script setup lang="ts">
import { toast } from "gooey-toast";

const save = async () => {
  await toast.promise(fetch("/api/save", { method: "POST" }), {
    loading: { title: "Saving" },
    success: { title: "Done", description: "Everything is synced." },
    error: { title: "Failed", description: "Please retry." },
  });
};
</script>

<template>
  <button @click="save">Save</button>
</template>

API

• toast.show(options)
• toast.success(options)
• toast.error(options)
• toast.warning(options)
• toast.info(options)
• toast.action(options)
• toast.promise(promiseOrFactory, options)
• toast.dismiss(id)
• toast.clear(position?)
• mountToaster(options) / createToaster(options)
• configureToaster(options)
• unmountToaster()

Options reference

ToastOptions

Used by toast.show, toast.success, toast.error, toast.warning, toast.info, and toast.action.

ToastPromiseOptions<T>

Used by toast.promise(promiseOrFactory, options).

ToasterOptions

Used by mountToaster, createToaster, and configureToaster.

Behavior defaults

• Hover pauses dismiss timers and timeout bars; leaving resumes from the remaining time.
• Dismissed toasts animate out before leaving the stack.
• description content is collapsed by default and expands on hover/autopilot.
• Swipe up/down beyond ~30px dismisses a toast.
• toast.* auto-mounts a default toaster if you do not mount one manually.

Debug playground

When you need to verify and tune the current toast behavior locally, use the built-in playground:

npm run playground

Then open http://localhost:8080.

It includes:

• quick actions for each toast.* state
• promise success/error scenarios
• controls for position, duration, roundness, fill, and autopilot timings
• live snapshot of DOM state ([data-gooey-toast], viewport counts, CSS vars)
• event log for lifecycle checks

The playground also exposes helper functions in the browser console via window.__gooeyToastDebug (snapshot(), logs(), burst(), dismissLast(), clear()).

Styling

The package ships with styles.css and uses stable data attributes like [data-gooey-toast] for targeting. You can also pass class names through options.styles to style title, description, badge, and button per toast.

Release and package automation

• Push and PR runs are validated by CI (.github/workflows/ci.yml).
• Pushes to main rebuild and deploy the demo to GitHub Pages (.github/workflows/pages.yml).
• Tagging vX.Y.Z triggers publish flow (.github/workflows/publish.yml).
• Publish flow validates tag/version, builds artifacts, publishes to npm, attaches a release tarball plus sha256sum.txt, emits build provenance, and creates a GitHub Release with generated notes.

Project hygiene

• Contribution guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md
• Issue and PR templates are in .github/