fast-alert

Ultra-lightweight, zero-dependency toast & alert library for the browser. One function, no CSS import, no setup.

• 🪶 Tiny — ~2 kB min+gzip, zero dependencies
• 🎨 Presets — success, error, warning, info with sensible colors
• 📍 7 positions — top, bottom, center and all four corners
• 📚 Stacking — multiple alerts stack instead of overlapping
• ⏱️ Progress bar — countdown indicator, pauses on hover
• 🔒 Safe by default — messages render as plain text (no XSS)
• ♿ Accessible — role="alert" / role="status", respects prefers-reduced-motion
• 🟦 Typed — TypeScript definitions included

Installation

npm install fast-alert

Or straight from a CDN:

<script type="module">
  import showAlert from 'https://esm.run/fast-alert';
  showAlert.success('Hello from the CDN!');
</script>

Quick start

import showAlert from 'fast-alert';

showAlert('Plain neutral toast');

showAlert.success('Saved!');
showAlert.error('Something went wrong');
showAlert.warning('Disk space is low');
showAlert.info('New version available');

// Full control
showAlert('Profile updated', {
  type: 'success',
  position: 'top-right',
  duration: 5000,
  closable: true,
});

Options

showAlert(message, options?)

| Option | Type | Default | Description | | ----------------- | ------------------- | ----------- | ------------------------------------------------------------------ | | type | string | 'default' | 'default' | 'success' | 'error' | 'warning' | 'info' | | position | string | 'top' | 'top', 'bottom', 'center', 'top-left', 'top-right', 'bottom-left', 'bottom-right' | | duration | number | 3000 | Auto-dismiss after N ms. 0 makes the alert sticky. | | closable | boolean | false | Show a close (×) button. | | dismissOnClick | boolean | false | Dismiss when the alert is clicked. | | pauseOnHover | boolean | true | Pause the countdown while hovered. | | progress | boolean | true | Show the countdown progress bar. | | width | string | content | CSS width of the alert box, e.g. '320px'. | | textColor | string | preset | Overrides the preset text color. | | backgroundColor | string | preset | Overrides the preset background color. | | icon | string | false | preset | Custom icon character, or false to hide it. | | html | boolean | false | Render the message as HTML. Only for trusted content. | | className | string | — | Extra CSS class(es) for custom styling. | | onClose | () => void | — | Called after the alert is removed. |

Closing programmatically

showAlert returns a handle:

const alert = showAlert('Uploading…', { duration: 0 }); // sticky
// later:
alert.close();

Custom styling

Pass a class and style it yourself:

showAlert('Branded toast', { className: 'my-toast', icon: false });

.my-toast {
  background: linear-gradient(135deg, #667eea, #764ba2) !important;
  border-radius: 999px;
}

Migrating from v1

The v1 positional signature still works and keeps its old defaults (red, centered):

showAlert('Hello', '300px', 'white', 'red', 'top', 1000); // still fine

New code should use the options object. Notable v2 changes:

• Messages are rendered as plain text by default (v1 used innerHTML, which was an XSS risk). Use { html: true } for trusted HTML content.
• showAlert('msg') with no other arguments now shows a neutral dark toast at the top instead of a red one in the center.
• The fading bottom border was replaced by a countdown progress bar.
• The package is now ESM (import); modern Node also supports require() of ESM.

License

MIT © Shota Pertakhia