brents-toasts

A simple drop-in vanilla and beginner friendly toast system

Demo live under: https://brentspine.github.io/brents-toasts/

This is a rewrite of an old optimistic previous attempt, that I used on various projects: https://github.com/brentspine/tinder-but-for-horses/blob/main/scripts/toasts.js

Install

npm

npm install brents-toasts

import { toasts, ToastColor, ToastBuilder } from 'brents-toasts';

yarn - same package, if you'd rather use yarn instead of npm:

yarn add brents-toasts

CDN / script tag

No build step, no module system required - served via jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/brents-toasts/dist/index.umd.min.js"></script>
<script>
  BrentsToasts.toasts.showToast('Hello, toast.');
</script>

Prefer unpkg instead? Same UMD build, works as a drop-in alternative:

<script src="https://unpkg.com/brents-toasts/dist/index.umd.min.js"></script>

Quick start

toasts.showToast('Saved!', { color: ToastColor.SUCCESS, title: 'Done' });

// or the fluent builder - same options under the hood
new ToastBuilder('Saved!').asSuccess().withTitle('Done').show();

Full walkthrough, including the other supported call shapes: Getting started.

Features

• Buttons - plain action buttons, a ready-made close button, and a confirm-before-action button with its own pending/done states.
• Multi-step buttons - the general-purpose state machine behind confirm/copy buttons, for your own custom multi-click flows.
• Details - expandable, copyable extra info attached to a toast without cluttering the main message.
• Lifecycle - remove/update toasts in place, animate an update with a transition, or tie a toast to a Promise's loading/success/error states.
• Timers - pause/resume/reset/extend a toast's auto-dismiss countdown, or read it back live.
• Per-toast data - attach a payload to a toast so one shared button handler can act on many toasts.
• Progress bar - a thin bar synced to the auto-dismiss countdown, or driven manually for real progress.
• Animations - a pluggable entrance/exit/reflow engine (slide/fade/none built in, register your own).
• Config - library-wide or page-scoped defaults, six stacking positions, per-position capacity limits, responsive collapsing on narrow screens, and independent opt-outs for the toast card's look (injectStyles: false) and its positioning/stacking CSS (injectLayoutStyles: false), for a custom design system or a strict CSP.
• Theming - every color is a CSS custom property, overridable per-toast or library-wide, with automatic close-icon contrast.
• Icons - opt-in icon rendered next to the message: built-in severity icons, an image URL, a CSS class, a custom Node, or your own renderer function, plus automatic pending/success/error icons for promise().
• Localization - built-in en/de/es/fr chrome text with custom overrides, plus a standalone pre-translated action-word utility.

TypeScript-first: full .d.ts types ship with every build, documented via JSDoc - your editor's hover/autocomplete covers most of the day-to-day API on its own.

Documentation

• docs/guide/ - the full guide, one topic per page (linked above).
• Live demo & playground - try every option interactively and copy the generated code.
• Claude Skill - accurate, hallucination-resistant guidance for AI agents writing code against this library. Install as a Claude Code plugin: /plugin marketplace add brentspine/brents-toasts then /plugin install brents-toasts@brents-toasts. No install step needed either - copy docs/ into your own project's .claude/skills/brents-toasts/ for the same effect.
• Changelogs and GitHub Releases - what changed in each version.

License

Apache-2.0