Getting Started
NextToast is a lightweight, zero-dependency toast notification system for Next.js. It’s built to be fast, simple, and predictable — with a clean API for success, error, promise, confirm, and custom.
Add the package with pnpm, npm, or bun.
Place <NextToast /> in your root layout.
Call toast.* from client components.
Installation
Install next-toast using your preferred package manager. If you’re using a monorepo, install it in the app package that renders the Next.js UI.
Click to trigger the toast. Switch to Code to copy.
- NextToast has no runtime dependencies.
- Works with the Next.js App Router and Client Components.
- Mount the renderer
<NextToast />only once.
Add NextToast to your app
NextToast renders notifications through a single renderer component: <NextToast />. Place it once in your app shell, typically in app/layout.tsx. You can mount it in server components (like the root layout) because it only renders UI and subscribes to updates internally.
Click to trigger the toast. Switch to Code to copy.
Mounting multiple <NextToast /> components can cause duplicated stacks or confusing behavior. Keep a single instance at the app root.
Render your first toast
Use the toast API from client components (components with "use client"). A toast call returns an id, which you can use to update or dismiss that toast later.
Click to trigger the toast. Switch to Code to copy.
Where should I call toast?
- Click handlers and UI events (buttons, form submit)
- After successful mutations (save, delete, update)
- Error handlers for user-visible failures
- Server Components (no client-side effects)
- Rendering time side effects (toasts should be user-driven)
Recommended patterns
Use toast.promise for async actions
For async work (save, upload, delete), prefer toast.promise. It automatically handles loading and swaps to success or error based on the promise result.
Click to trigger the toast. Switch to Code to copy.
Use confirm for destructive actions
Use toast.confirm for destructive actions when a modal would be too heavy. Keep the message explicit: what is being deleted and what the impact is.
Click to trigger the toast. Switch to Code to copy.
Avoid toast spam
Prefer one toast per user action. If your UI can fire multiple toasts quickly, consider clearing older messages before showing a new, critical toast.
Click to trigger the toast. Switch to Code to copy.
Troubleshooting
Toast not showing
- Confirm
<NextToast />is mounted inapp/layout.tsx. - Ensure the code calling
toast.*is in a client component. - Check you didn’t mount multiple toast renderers.
Using toast in server components
Server components can’t run client-side interactions. If you need to show a toast after a server action, trigger it from the client after the action returns (for example, in a click handler or a mutation callback).
Next steps
Continue to Toasts to explore all toast types and options.