🥐 nice-toaster

The toast that’s actually nice.
Beautiful, customizable, and modern notifications for React — with system notification support, vibration, progress bars, and more.
From minimal to advanced, make your app pop!

🌟 What is nice-toaster?

A lightweight, beautiful, and highly customizable toast notification library for React. It supports system notifications, vibration, progress bars, and more — all with a simple API.

• Perfect for beginners: Easy to set up, minimal code required.
• Loved by pros: Advanced features, theming, and extensibility.

🚀 Features at a Glance

• One-liner API: toast.success, toast.error, toast.warn, toast.info
• 5 templates: default, classic, cyber, fuzzy, pretty
• Light & dark themes
• 6 positions: top/bottom, left/center/right
• Reverse order: Show newest toasts at the top or bottom (default: top)
• Description: Add a summary below the main message
• Hold: Toast stays until clicked
• Vibration (if supported)
• Timer/progress bar
• System notification (desktop only)
• Mobile & desktop support
• Super lightweight

📦 Installation

npm install nice-toaster

🟢 Quick Start (Beginner)

1. Add the Toaster to your App:

import React from 'react';
import toast, { SetupNiceToaster } from 'nice-toaster';

function App() {
  return (
    <>
      <SetupNiceToaster />
      <button onClick={() => toast.success('Hello from Nice Toaster!')}>
        Show Toast
      </button>
    </>
  );
}

2. That's it! Click the button to see a toast.

🧑‍💻 How It Works

• <SetupNiceToaster /> — Place this once, near the root of your app. It sets up the toast container.
• toast.success, toast.error, toast.warn, toast.info — Call these anywhere to show a toast.

⚡ Advanced Usage

<SetupNiceToaster
  settings={{
    theme: 'dark',         // 'light' | 'dark'
    template: 'pretty',    // 'default' | 'classic' | 'cyber' | 'fuzzy' | 'pretty'
    position: 'bottom-right', // 'top-center', ...
    reverseOrder: true,    // Show newest toasts at the top (default)
  }}
/>

<button
  onClick={() =>
    toast.success('Saved successfully!', {
      description: 'Your changes have been saved and synced to the cloud.',
      hold: true,            // Toast stays until clicked
      vibration: true,       // Vibrate device (if supported)
      time: 8000,            // Show for 8 seconds (ignored if hold is true)
      timer: true,           // Show progress bar (ignored if hold is true)
      notification: true,    // Also show system notification (desktop only)
    })
  }
>
  Show Advanced Toast
</button>

🛠️ API Reference

<SetupNiceToaster settings={...} />

| Option | Type | Default | Description | | -------------- | --------- | -------------- | ----------- | | theme | string | 'light' | 'light' or 'dark' | | template | string | 'default' | 'default', 'classic', 'cyber', 'fuzzy', 'pretty' | | position | string | 'top-center' | 'top-center', 'top-right', 'top-left', 'bottom-center', 'bottom-right', 'bottom-left' | | reverseOrder | boolean | true | If true, newest toasts appear at the top; if false, at the bottom |

toast.success(message, options) (also: error, warn, info)

| Option | Type | Default | Description | | -------------- | --------- | -------------- | ----------- | | message | string | — | Main message (required) | | description | string | — | Optional summary/description below the main message | | hold | boolean | false | If true, toast stays until clicked | | vibration | boolean | false | Vibrate device (if supported) | | time | number | 5000 | Duration in ms (ignored if hold is true) | | timer | boolean | false | Show progress bar (ignored if hold is true) | | notification | boolean | false | Also show system notification (desktop only) |

🎨 Templates & Themes

• default: Modern, rounded, subtle shadow
• classic: Bold, full-width, flat
• cyber: Futuristic, blurred, colored borders
• fuzzy: Soft, minimal, gentle colors
• pretty: Elegant, pill-shaped, vibrant backgrounds

Switch templates by changing the template value in your settings!

Themes: Use theme: 'light' or theme: 'dark' for instant style changes.

📍 Positioning & Order

• Positions:

  • 'top-center' (default)
  • 'top-right'
  • 'top-left'
  • 'bottom-center'
  • 'bottom-right'
  • 'bottom-left'

• Reverse Order:

  • If reverseOrder: true (default), newest toasts appear at the top of the stack.
  • If reverseOrder: false, newest toasts appear at the bottom.

🧑‍🔬 Advanced Features

• System Notifications:

  • Set notification: true in toast options.
  • Only works on desktop browsers with permission.
  • Not supported on mobile or on 0.0.0.0 dev servers (use localhost or HTTPS).

• Vibration:

  • Set vibration: true in toast options.
  • Works on supported devices (mostly mobile).

• Hold-to-dismiss:

  • Set hold: true in toast options.
  • Toast stays until user clicks it.

• Timer/Progress Bar:

  • Set timer: true in toast options.
  • Shows a visual countdown (ignored if hold is true).

🎮 Playground

Try all features live: nice-toaster-playground.vercel.app

• Change theme, template, position, reverse order, and more.
• See code samples update in real time.

❓ FAQ / Troubleshooting

• Why don't system notifications work?
  • Make sure you're on a desktop browser, using localhost or HTTPS, and have granted notification permission.
• Why doesn't vibration work?
  • Only supported on some mobile devices/browsers.
• Can I use this in Next.js, Vite, or CRA?
  • Yes! It works with all major React setups.
• How do I style the toasts?
  • Use the template and theme options, or override CSS for full control.

👨‍💻 Author

Made with ❤️ by Muhammad Jazib

📝 License

MIT