I Built a Toast Library for React & Next.js - Here’s How It Works 🍞

If you’ve worked on modern web applications, you’ve probably used toast notifications. “Saved successfully.” “Something went wrong.” “Uploading…” “File deleted - Undo” They look simple from the outside, but toast notifications become surprisingly useful once an application has many user interactions. I wanted something that was simple to use, lightweight, modern-looking, and flexible enough for common React and Next.js projects. That’s why I built your-toast - a small toast notification library for React and Next.js with a modern glass-style UI and a simple API. 🍞 Why Your Toast? In most applications, I don't need a huge notification system. Usually, I just need something like: toast.success("Profile updated!"); The goal behind your-toast is exactly that: Keep the API simple while giving developers enough control when they need it. It supports common notification patterns without requiring complicated setup. 🚀 How It Works The basic architecture is simple. There are three main parts: Toast API ↓ Toast Store ↓ YourToastProvider ↓ UI When you call: toast.success("Saved successfully!"); the toast API creates a toast object and sends it to an internal store. The store keeps track of active toasts. Then YourToastProvider listens to the store and renders the current toast notifications. So developers don't need to manually manage toast state inside every component. ⚛️ React Usage For a React/Vite application, you can mount the provider once: import { YourToastProvider, toast } from "your-toast"; function App() { return ( <> toast.success("Saved!")}> Save ); } After that, you can trigger notifications wherever you need them. toast("Hello!"); toast.success("Saved successfully!"); toast.error("Something went wrong!"); toast.warning("Please check your input."); toast.info("New update available."); toast.loading("Uploading..."); The API stays intentionally small and readable. ▲ Next.js App Router One thing I wanted to handle properly was the difference between normal React applications and Next.js App Router. In Next.js, the root layout can remain a Server Component. Instead of making the entire layout client-side, your-toast provides a dedicated client entry: import { YourToastProvider } from "your-toast/provider"; Then: export default function RootLayout({ children }) { return ( {children} ); } You don't need to add "use client" to the root layout. Then from a Client Component: "use client"; import { toast } from "your-toast"; export default function Button() { return ( toast.success("Done!")}> Click me ); } This keeps the Client Component boundary explicit without turning the whole application into a client component. That was one of the architectural details I specifically wanted to get right. ⚡ Promise-Based Toasts One of my favorite features is toast.promise() . Instead of manually handling loading, success, and error states: toast.loading("Loading..."); // do something toast.success("Completed!"); you can connect the toast directly to a promise: toast.promise(fetchData(), { loading: "Loading...", success: "Data loaded!", error: "Something went wrong.", }); It can also work with dynamic results: toast.promise(fetchData(), { loading: "Loading...", success: (data) => Loaded ${data.name}, error: () => "Failed to load data.", }); This makes async UI feedback much easier to manage. 🔁 More Control When You Need It Sometimes a notification needs to stay under your control. For example: const id = toast.loading("Uploading..."); Then after the upload: toast.update(id, { title: "Upload complete!", type: "success", }); You can also dismiss a specific toast: toast.dismiss(id); Or dismiss all active notifications: toast.dismiss(); You can customize duration and descriptions as well: toast.success("Profile updated!", { description: "Your changes have been saved.", duration: 3000, }); And for actions: toast("File deleted", { action: { label: "Undo", onClick: () => { console.log("Undo clicked"); }, }, }); 🧩 A Small Library, But With Real Architecture Although the package is small, I didn't want it to be just a component with some setTimeout() calls. The library uses an external store to keep toast state separate from the UI. React's useSyncExternalStore is used to safely subscribe the provider to that store. The package is also built with: - TypeScript - ESM - CommonJS - TypeScript declaration files - React 18+ - React 19 - Next.js App Router support The result is a small package that can fit into different React application setups without adding unnecessary dependencies. 🎯 When Would I Use It? I think your-toast fits especially well when an application needs frequent UI feedback for things like: - Form submissions - Authentication - API requests - File uploads - CRUD operations - Saving settings - Delete/undo actions - Background operations - Success/error feedback For these common cases, I wanted the experience to be as simple as: toast.success("Everything is ready!"); No complicated configuration. Just feedback when the user needs it. 🚧 Still Improving your-toast is still growing. Some ideas on the roadmap include: - Better animations - More advanced glass UI - Theme system - Mobile improvements - Progress indicators - Swipe-to-dismiss - Custom icons - Custom React content So this isn't a “finished forever” library. I'm building it, using it, and improving it based on real use cases and developer feedback. ⭐ Try It & Help Improve It If you're working with React or Next.js and need a simple toast library, you can check out your-toast : NPM: https://www.npmjs.com/package/your-toast GitHub: https://github.com/masaudahmod/your-toast If you find it useful, a ⭐ on GitHub would mean a lot. And if you have an idea, find a bug, or think something could be improved, feel free to open an issue or share your suggestion. Developer feedback is one of the best ways to make an open-source project better. 💭 Final Thought Building your-toast reminded me that even a small UI feature can involve interesting engineering decisions. A toast may look like a tiny notification on the screen, but behind that notification there’s state management, rendering, accessibility, package architecture, framework compatibility, and developer experience. And that's exactly what I enjoyed about building it. Sometimes, small projects are where you learn the most. 🍞 Top comments (0)