your-toast

v0.1.2

Published

19 days ago

Modern toast notification library for React and Next.js with glass UI, promise support, and clean API

your-toast 🍞

npm GitHub stars

Modern toast notification library for React apps.

✨ Clean & intuitive API 🍏 Glass-style UI ⚡ Lightweight & fast 🔄 Promise support 🎯 Fully controllable

🚀 Features

🔥 Minimal and powerful toast() API
🎨 Multiple toast variants
⚡ Promise-based notifications with toast.promise()
📦 Automatic toast stack management
🔁 Update and dismiss notifications programmatically
⏱ Configurable auto-dismiss duration
🍏 Modern glass-style UI
🌙 Dark-mode ready
🎯 Action buttons
🔷 TypeScript support
⚛️ React 18+ support
▲ Next.js App Router friendly

📦 Installation

npm install your-toast

⚛️ React / Vite

For client-side React applications such as Vite, import the provider and toast API directly:

import { YourToastProvider, toast } from "your-toast";

export default function App() {
  return (
    <>
      <YourToastProvider />

      <button onClick={() => toast("Hello from your-toast 🚀")}>
        Show Toast
      </button>
    </>
  );
}

The provider only needs to be mounted once in your application.

▲ Next.js App Router

your-toast supports the Next.js App Router without making your root layout a Client Component.

1. Add the provider

Import the provider from the dedicated client entry:

import { YourToastProvider } from "your-toast/provider";

Then add it to your root layout:

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}

        <YourToastProvider />
      </body>
    </html>
  );
}

You do not need to add "use client" to your root layout.tsx.

2. Trigger a toast from a Client Component

"use client";

import { toast } from "your-toast";

export default function SaveButton() {
  return (
    <button onClick={() => toast.success("Saved successfully!")}>Save</button>
  );
}

Why `your-toast/provider`?

The provider is exposed through a dedicated client entry point:

import { YourToastProvider } from "your-toast/provider";

This keeps the Next.js Client Component boundary explicit while allowing your root layout to remain a Server Component.

🎯 Toast Variants

Default

toast("Default message");

Success

toast.success("Saved successfully!");

Error

toast.error("Something went wrong!");

Warning

toast.warning("Please check your input.");

Info

toast.info("New update available.");

Loading

toast.loading("Uploading...");

⚙️ Toast Options

Customize a toast with additional options:

toast.success("Profile updated!", {
  description: "Your profile has been saved successfully.",
  duration: 3000,
});

Available options

{
  description?: string;
  duration?: number;
  action?: {
    label: string;
    onClick: () => void;
  };
}

🎯 Action Toast

Add an interactive action to a toast:

toast("File deleted", {
  action: {
    label: "Undo",
    onClick: () => {
      console.log("Undo clicked");
    },
  },
});

⚡ Promise Toast

Show loading, success, and error states automatically:

toast.promise(fetchData(), {
  loading: "Loading...",
  success: "Data loaded!",
  error: "Something went wrong.",
});

You can also generate messages dynamically from the resolved value or error:

toast.promise(fetchData(), {
  loading: "Loading...",
  success: (data) => `Loaded ${data.name}`,
  error: (error) => "Failed to load data.",
});

toast.promise() returns the original promise result, so it can still be awaited:

const data = await toast.promise(fetchData(), {
  loading: "Loading...",
  success: "Data loaded!",
  error: "Failed to load data.",
});

🔁 Update a Toast

Every toast returns an ID:

const id = toast("Uploading...");

Update it later:

toast.update(id, {
  title: "Upload complete!",
  type: "success",
});

You can also update the description or duration:

toast.update(id, {
  title: "Almost done...",
  description: "Processing your file.",
  duration: 3000,
});

❌ Dismiss Toasts

Dismiss a specific toast:

const id = toast("Hello!");

toast.dismiss(id);

Dismiss all active toasts:

toast.dismiss();

⏱ Duration

Toasts automatically disappear after their duration:

toast("This disappears after 2 seconds.", {
  duration: 2000,
});

Loading toasts remain visible until they are updated or dismissed:

const id = toast.loading("Uploading...");

// Later
toast.update(id, {
  title: "Upload complete!",
  type: "success",
});

🔷 TypeScript

your-toast is written with TypeScript and provides built-in type definitions.

The package includes typed APIs for:

Toast variants
Toast options
Toast actions
Promise messages
Toast updates

Example:

toast.success("Success!", {
  description: "Everything went well.",
  duration: 3000,
});

Your editor will provide autocomplete and type checking automatically.

🎨 Supported Types

Type API

Default toast() Success toast.success() Error toast.error() Warning toast.warning() Info toast.info() Loading toast.loading() Action toast() with action

🛠 Developer Friendly

Simple and predictable API
Minimal setup
No external UI dependencies
Built-in TypeScript definitions
React 18+ compatible
React 19 compatible
Next.js App Router friendly
Vite friendly
ESM + CommonJS builds
Lightweight package

🗺 Roadmap

🍏 Advanced glass UI polish
🎞 Improved animations
🎨 Theme system
📱 Mobile UX optimization
📍 Toast positioning system
📊 Progress indicators
⏸ Pause on hover / focus
👆 Swipe-to-dismiss
🔔 Custom icons
🌐 RTL support
⚛️ Custom React content

📄 License

MIT

👨‍💻 Author

Masaud Ahmod

⭐ Support

If you find this useful, consider giving a ⭐ on GitHub: 👉 https://github.com/masaudahmod/your-toast