Customizable Growl/Toast Alerts with LocalNotification.js

LocalNotification is a lightweight JavaScript library that creates customizable, temporary, growl-style or toast-style notifications for client-side feedback.

Its main goal is to display non-intrusive, brief messages to the user, typically in response to an action like a form submission or an asynchronous operation completing.

Features:

• Place notifications in corners like top-right, bottom-left, etc.
• Set how long notifications stay visible (in milliseconds), or disable auto-close entirely.
• The timer pauses automatically when the user hovers over the notification or switches browser tabs/windows.
• Control appearance with CSS, including colors, icons, and custom style objects.
• Visually indicates the remaining time before auto-close.
• Includes an optional close button.

See it in action:

How to use it:

1. Add LocalNotification’s CSS and JavaScript files to your HTML page.

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

2. Create a notification by instantiating the LocalNotification class with your desired options:

const notification = new LocalNotification({
  text: 'A Basic Notification',
  // More options here
});

// Trigger on an event, like a button click
document.getElementById('saveButton').addEventListener('click', () => {
  new LocalNotification({
    text: 'Settings saved.',
  });
});

3. Customize the behavior and appearance of your notifications using these options passed into the constructor:

• text (string): The message to display.
• position (string): Where the notification appears (top-right, top-left, bottom-right, bottom-left, top-center, bottom-center).
• autoClose (number): Duration in milliseconds before auto-closing. 0 disables it.
• canClose (boolean): Show a manual close button?
• showProgress (boolean): Display the progress bar?
• pauseOnHover (boolean): Pause timer on mouse hover?
• pauseOnFocusLoss (boolean): Pause timer when the browser tab loses focus?
• style (object): An object containing CSS properties (camelCase or kebab-case) to apply directly to the notification element.
• closeButtonColor (string): CSS color for the close button text.
• icon (string): HTML string or Unicode character for an icon
• iconColor (string): CSS color for the icon.
• progressBarColor (string): CSS color for the progress bar.
• onClose (function): A callback function executed when the notification is closed (either manually or automatically).

const notification = new LocalNotification({
  position: 'top-right',
  autoClose: 5000,
  canClose: true,
  showProgress: true,
  pauseOnHover: true,
  pauseOnFocusLoss: true,
  style: {},
  closeButtonColor: '#000',
  icon: null,
  iconColor: '#000',
  progressBarColor: '#E4235D',
  onClose: () => { },
});

4. Pro tips:

• Keep notification text concise. These aren’t meant for paragraphs.
• Use onClose for any cleanup logic specific to that notification disappearing.
• Be mindful of autoClose duration – too short and users miss it, too long and it becomes annoying. 5 seconds is a reasonable default.

FAQs

Q: How are multiple notifications handled? Do they stack?
A: Yes. The library creates a container for each position (top-right, etc.). When you create a new notification for a position that already has one, it appends the new notification within that container. The default CSS handles stacking (e.g., using flexbox column layout on the container).

Q: Can I trigger notifications programmatically based on server events (e.g., via WebSockets)?
A: Absolutely. Since you trigger a notification by calling new LocalNotification(...), you can place that call inside any JavaScript logic, including WebSocket message handlers or after fetch requests complete.

Q: How can I customize the appearance beyond the basic options?
A: For significant changes, edit the notification.css file. Target the .notification, .notification-container, .close-button, .progress-bar, etc., classes. For one-off style overrides on a specific notification instance, use the style option object.

Q: Is there built-in support for different notification types (success, error, info, warning)?
A: Not explicitly via a type option. However, you can easily implement this yourself by passing different icon, iconColor, progressBarColor, and style options based on the type of message you want to show. You could wrap LocalNotification in your own helper function for this.