Toasty-Bite

Toasty-Bite is a lightweight customizable, vanilla JS toast notification library

See CHANGELOG.md for release history.

Demo

The live demo is hosted on my personal site, linked from here rather than served via GitHub Pages:

🔗 Live demo: add your personal-site URL here once it's uploaded

Demo/index.html (with its own demo.css/demo.js for the playground UI) loads the actual library from a jsDelivr CDN link pointing at this repo's src/ folder — not a local relative path — so the exact same Demo/ folder works no matter where it's hosted: locally, on GitHub, or on your personal site, without needing to copy the library files alongside it. Before publishing, open Demo/index.html and replace the YOUR-USERNAME/YOUR-REPO placeholders in the two CDN links with your real GitHub username and repo name.

⚠️ Two things that CDN link depends on: the repo needs to be public, and @main always serves whatever's on that branch right now. For a demo that shouldn't shift under you, pin it to a release tag instead once you've cut one — e.g. @v1.0.0 instead of @main — otherwise a future push to src/ changes the live demo immediately.

You can still open Demo/index.html straight from disk for local testing; it'll just fetch the library from the CDN instead of a local file, so it needs an internet connection.

Features

• 🎯 6 anchor positions — top/bottom × left/center/right, always full-width on mobile (never centered)
• 🌗 Dark & light themes — neither uses pure black/white; switching re-themes toasts already on screen, live
• ⏱ Per-type timing — info/success 4s, warning 7s, error waits for manual dismiss — all independently overridable
• 📚 Smart stacking — up to 3 visible at once, extras queue and slide in as slots free up
• ⏸ Hover-to-pause — hovering a toast pauses its countdown and freezes its progress bar
• 📊 Animated progress bar — colored to match the toast type, drains over the toast's duration
• 🎨 Deep customization — position, theme, background, title/message color, dismiss button styling, icon color, and font family, configurable globally or per-call
• ✅ Intentional dismissal — close-button only, so useful toasts can't be swiped away by a stray click
• ♿ Accessible by default — role="status"/role="alert" + aria-live, and respects prefers-reduced-motion
• ⚡ Lightweight engine — stacking and the progress bar are driven by CSS transitions/animations, not a per-frame JS loop, so there's no standing CPU cost while toasts are idle or animating

Installation

All library files live in src/. Grab them from there and drop them into your own project — for production, use the minified pair; use the unminified source in dev or if you want to fork/reskin it.

<link rel="stylesheet" href="src/toast.min.css">
<script src="src/toast.min.js"></script>

(Adjust the src/ prefix to wherever you actually place the files in your own project — it's just this repo's folder name, not a required path.)

Or via npm:

npm install toasty-bite

import 'toasty-bite/css';       // or 'toasty-bite/min.css' for production
import Toast from 'toasty-bite'; // also available as window.Toast if loaded via <script>

Subpath imports are available for the minified build and both stylesheets:

import Toast from 'toasty-bite/min'; // minified JS
import 'toasty-bite/css';            // unminified CSS
import 'toasty-bite/min.css';        // minified CSS

TypeScript types are bundled — no @types package needed.

That's it — no build step, no config file.

Documentation

Quick start

Toast.info('Update available', 'Version 2.15 is ready');
Toast.success('Saved to drafts', 'Changes auto-backed up');
Toast.warning('Quota almost up', '92% of plan used');
Toast.error('Connection lost', 'Retrying in 5 seconds');

Toast.info/.success/.warning/.error also accept a single options object instead of (title, message, options), same as Toast.show():

Toast.success({ title: 'Saved to drafts', titleColor: '#00e676' });

Full control, per toast

Toast.show({
  type: 'info',            // 'info' | 'success' | 'warning' | 'error'
  title: 'Custom toast',
  message: 'Optional supporting line',
  duration: 5000,           // ms; overrides the type default for this toast. Infinity = manual only
  titleColor: '#e6f0ff',    // overrides just this toast's title color
  onDismiss: () => {}       // fires once the toast is fully removed
});

Toast.dismiss(id);   // dismiss one by id (returned from show/info/success/...)
Toast.dismissAll();  // clear everything, including anything queued

Global customization

Use Toast.configure() once at startup (or any time after) to set defaults for every toast that follows:

Toast.configure({
  position: 'bottom-right',   // see Options reference below
  theme: 'light',             // 'dark' (default) or 'light'
  background: '#101522',      // any valid CSS background (color, gradient, etc.)
  titleColor: '#12172a',
  messageColor: '#5b6474',
  dismissColor: '#4b5568',        // the ✕ icon
  dismissBackground: 'rgba(15,23,42,0.06)', // the ✕ button's background
  iconColor: '#3b82f6',           // the leading type icon (info/success/warning/error)
  fontFamily: '"Inter", sans-serif',
  duration: { info: 6000, warning: 9000, success: 5000, error: 10000 } // each type is independent
});

Step by step:

1. Load the library first. toast.min.css + toast.min.js need to be on the page before you call anything.
2. Call Toast.configure({...}) once at startup, before firing your first toast — it only affects toasts created after it runs.
3. Set position and theme for your anchor corner and light/dark look.
4. Set colors and fontFamily if you want to match your brand — every property is optional and independent.
5. Set duration per type if the 4s/4s/7s/manual defaults don't fit your product.
6. Fire toasts as normal (Toast.info(), .success(), .warning(), .error(), .show()) — they pick up your config automatically.
7. To undo one override, call configure() again with that key set to null, e.g. Toast.configure({ titleColor: null }).

A per-call option (passed to show()/info()/etc.) always wins over the global configure() value for that one toast.

Options reference

| Option | Controls | |----------------------|----------| | position | anchor corner — see list below | | theme | 'dark' (default) or 'light' | | background | the toast card's background | | titleColor | the title text | | messageColor | the message text | | dismissColor | the ✕ icon inside the dismiss button | | dismissBackground | the dismiss button's own background | | iconColor | the leading type icon (and its tinted backdrop) | | fontFamily | font family for both title and message | | duration | object keyed by type (info/success/warning/error), in ms |

position accepts: top-right (default), top-left, top-center, bottom-right, bottom-left, bottom-center. On mobile the stack always becomes full-width, anchored to whichever edge (top/bottom) the chosen position uses — never centered. Bottom-anchored toasts grow upward from the anchor edge so they stay fully within the viewport.

Pass null (or '') to any color/font/background option to clear the override and fall back to the active theme's default.

error defaults to Infinity (manual-dismiss only) — pass a finite number in duration.error to make it auto-dismiss too.

Behavior notes

• Dismissal is close-button only. Clicking anywhere else on a toast does nothing, so useful info can't be swiped away by accident. Hovering pauses the countdown and freezes the progress bar until the pointer leaves.
• Timing defaults: info 4s, success 4s, warning 7s, error never auto-dismisses. All overridable via duration.
• Progress bar is colored to match the toast type and drains from full to empty over the duration; omitted entirely for infinite-duration toasts.
• Stacking: up to 3 toasts shown at once, animated into their slot with a slight spring-like overshoot; a 4th+ toast queues and slides in — from the far end of the stack — as soon as a slot frees up.
• Z-index: the toast stack renders at the maximum CSS z-index (2147483647), so it stays above any other fixed/sticky UI on the host page.
• Live re-theme/re-anchor: calling configure({ position, theme }) smoothly re-anchors/re-themes toasts already on screen; other option changes only apply going forward.

Accessibility

Toasts use role="status" (role="alert" for errors) with aria-live so screen readers announce them. Users with prefers-reduced-motion enabled get instant opacity and position changes instead of animated transitions.

Project structure

├── src/                  # the library — this is what your project actually uses
│   ├── toast.js          # readable source
│   ├── toast.css
│   ├── toast.min.js      # minified, recommended for production
│   ├── toast.min.css
│   └── toast.d.ts        # TypeScript declarations
├── Demo/                 # the live playground — hosted separately, not needed in your own project
│   ├── index.html        # loads the library from a jsDelivr CDN link (see Demo section above)
│   ├── demo.css          # styling for the demo page itself
│   └── demo.js           # wires up the demo's buttons/controls to the library
├── package.json
├── LICENSE
└── README.md

License

MIT — see LICENSE for the full text. You're free to use, modify, and distribute this in personal or commercial projects; just keep the copyright notice.