notifybox

NotifyBox

A lightweight, TypeScript-first notification library for web applications. Zero dependencies, fully customizable, and easy to use. Supports both in-page toast notifications and native browser notifications.

Installation

pnpm add notifybox

Quick Start

Toast Notifications (In-Page)

import { notifications } from "notifybox";

// Show different types of toast notifications
notifications.success("Operation completed successfully!");
notifications.error("Something went wrong!");
notifications.warning("Please check your input");
notifications.info("Here's some information");

Browser Notifications (Native)

import { notifications } from "simple-notifications";

// Request permission first (or configure auto-request)
await notifications.requestBrowserPermission();

// Show browser notifications
await notifications.browserSuccess("Task completed!");
await notifications.browserError("Error occurred!");

// Or use mode option
await notifications.success("Done!", { mode: "browser" });

Advanced Usage

Automatic Mode Selection

// 'auto' mode uses browser notifications when page is hidden, toast when visible
notifications.info("New message received", { mode: "auto" });

Custom Configuration

import { NotificationManager } from "notifybox";

const customNotifications = new NotificationManager({
  defaultDuration: 6000,
  defaultPosition: "top-left",
  maxNotifications: 3,
  defaultMode: "auto",
  requestPermissionOnInit: true,
  fallbackToToast: true,
  browserNotificationOptions: {
    icon: "/my-app-icon.png",
    badge: "/my-badge.png",
  },
});

Rich Browser Notifications

notifications.info("New message from John", {
  mode: "browser",
  icon: "/user-avatar.jpg",
  image: "/message-preview.jpg",
  actions: [
    { action: "reply", title: "Reply", icon: "/reply-icon.png" },
    { action: "mark-read", title: "Mark as Read" },
  ],
  onClick: () => {
    // Handle notification click
    window.focus();
    // Navigate to message
  },
});

Toast Notifications with Custom Options

notifications.success("Success!", {
  mode: "toast",
  duration: 8000,
  position: "bottom-center",
  closable: false,
  onClick: () => console.log("Toast clicked!"),
  onClose: () => console.log("Toast closed!"),
});

Permission Management

// Check browser notification support
if (notifications.hasBrowserSupport()) {
  console.log("Browser notifications are supported");
}

// Check current permission status
if (notifications.hasBrowserPermission()) {
  console.log("Browser notifications are allowed");
}

// Request permission manually
const permission = await notifications.requestBrowserPermission();
if (permission === "granted") {
  console.log("Permission granted!");
}

Manual Control

// Create a notification that doesn't auto-dismiss
const notification = await notifications.info("Processing...", {
  duration: 0,
  mode: "toast",
});

// Later, remove it manually (only works for toast notifications)
if (notification instanceof NotificationElement) {
  notification.remove();
}

// Clear all toast notifications
notifications.clear();

API Reference

NotificationManager

The main class for managing notifications.

Constructor Options

interface NotificationConfig {
  defaultDuration?: number; // Default auto-dismiss time (4000ms)
  defaultPosition?: string; // Default position ('top-right')
  maxNotifications?: number; // Max concurrent toasts (5)
  className?: string; // Custom CSS class
  defaultMode?: NotificationMode; // 'toast' | 'browser' | 'auto'
  requestPermissionOnInit?: boolean; // Request permission on init (false)
  fallbackToToast?: boolean; // Fallback to toast if browser fails (true)
  browserNotificationOptions?: {
    // Default browser notification options
    icon?: string;
    badge?: string;
    image?: string;
  };
}

Methods

Toast & Browser Notifications

• show(message, options?) - Show notification with specified mode
• success(message, options?) - Show success notification
• error(message, options?) - Show error notification
• warning(message, options?) - Show warning notification
• info(message, options?) - Show info notification

Browser-Only Notifications

• browserSuccess(message, options?) - Force browser success notification
• browserError(message, options?) - Force browser error notification
• browserWarning(message, options?) - Force browser warning notification
• browserInfo(message, options?) - Force browser info notification

Utility Methods

• clear() - Remove all toast notifications
• requestBrowserPermission() - Request browser notification permission
• hasBrowserSupport() - Check if browser notifications are supported
• hasBrowserPermission() - Check if permission is granted

Notification Options

interface NotificationOptions {
  // Common options
  type?: "success" | "error" | "warning" | "info";
  duration?: number; // Auto-dismiss time (0 = never)
  onClick?: () => void; // Click handler
  onClose?: () => void; // Close handler

  // Mode selection
  mode?: "toast" | "browser" | "auto";

  // Toast-specific options
  position?:
    | "top-right"
    | "top-left"
    | "bottom-right"
    | "bottom-left"
    | "top-center"
    | "bottom-center";
  closable?: boolean; // Show close button (default: true)

  // Browser-specific options
  icon?: string; // Notification icon URL
  image?: string; // Large image URL
  badge?: string; // Small badge icon URL
  tag?: string; // Notification tag for grouping
  requireInteraction?: boolean; // Require user interaction to dismiss
  silent?: boolean; // Silent notification
  actions?: NotificationAction[]; // Action buttons
}

interface NotificationAction {
  action: string; // Unique action identifier
  title: string; // Button text
  icon?: string; // Button icon URL
}

Notification Modes

Toast Mode (mode: 'toast')

• Shows in-page notifications
• Customizable positioning and styling
• Hover to pause auto-dismiss
• Multiple notifications stack
• Always works (no permissions needed)

Browser Mode (mode: 'browser')

• Uses native browser notifications
• Appears outside the webpage
• Requires user permission
• Supports rich features (actions, images, badges)
• Works even when page is not visible

Auto Mode (mode: 'auto')

• Intelligent mode selection
• Uses browser notifications when page is hidden
• Uses toast notifications when page is visible
• Perfect for real-time applications

Permission Handling

The library handles browser notification permissions gracefully:

• Automatic Fallback: If browser notifications fail, it falls back to toast (configurable)
• Permission Caching: Remembers permission status to avoid repeated requests
• Graceful Degradation: Works perfectly even without browser notification support

Browser Compatibility

• Toast Notifications: All modern browsers
• Browser Notifications: Chrome 22+, Firefox 22+, Safari 6+, Edge 14+

Real-World Examples

Chat Application

const chatNotifications = new NotificationManager({
  defaultMode: "auto",
  requestPermissionOnInit: true,
  browserNotificationOptions: {
    icon: "/chat-icon.png",
  },
});

// New message notification
chatNotifications.info(`New message from ${sender}`, {
  mode: "auto",
  onClick: () => {
    window.focus();
    openChat(senderId);
  },
});

Form Validation

// Error notifications stay on page
notifications.error("Please fill in all required fields", {
  mode: "toast",
  duration: 6000,
  position: "top-center",
});

// Success can use browser notification
notifications.success("Form submitted successfully!", {
  mode: "browser",
  duration: 3000,
});

Background Tasks

// Long-running task completion
notifications.success("Export completed successfully!", {
  mode: "browser",
  requireInteraction: true,
  actions: [
    { action: "download", title: "Download File" },
    { action: "view", title: "View Results" },
  ],
});

Features

• 🎯 TypeScript First - Full type safety and IntelliSense support
• 🪶 Lightweight - No dependencies, minimal bundle size
• 🌐 Dual Mode - Toast and browser notifications in one package
• 🤖 Smart Auto Mode - Automatically chooses the best notification type
• 📱 Responsive - Mobile-friendly with adaptive layouts
• 🎨 Customizable - Easy to style and configure
• ♿ Accessible - Proper ARIA labels and keyboard support
• 🔔 Rich Browser Features - Actions, images, badges, and more
• 🛡️ Permission Management - Graceful handling of browser permissions
• 🚀 Performance - Efficient DOM management and animations

License

MIT