Sonner — Opinionated Toast Notification Component for React

Introduction

Sonner is a toast notification component for React that prioritizes beautiful defaults and developer experience. Rather than providing a low-level notification primitive, Sonner ships fully styled, animated toasts that work well out of the box. It handles stacking, positioning, dismissal, and promise tracking with a minimal API.

What Sonner Does

• Renders animated, stacked toast notifications with smooth enter/exit transitions
• Provides typed toast variants: success, error, warning, info, loading, and custom
• Tracks promises automatically showing loading, success, and error states
• Supports swipe-to-dismiss on mobile and hover-to-pause on desktop
• Allows rich content including custom JSX, action buttons, and descriptions

Architecture Overview

Sonner uses a singleton pattern where a single Toaster component mounts a portal for rendering toasts. The toast() function imperatively adds notifications to an internal queue. Each toast manages its own timer, animation state, and height measurement for stacking calculations. CSS transitions handle enter/exit animations while pointer events control the pause-on-hover behavior.

Self-Hosting & Configuration

• Add the Toaster component once at your app root
• Call toast() from anywhere in your application code
• Configure position (top-left, bottom-right, etc.) via Toaster props
• Customize theme to match your design system with CSS variables or the theme prop
• Works with Next.js App Router, Remix, and any React framework

Key Features

• Promise-based toasts that automatically track async operation states
• Smooth height-based stacking animation when multiple toasts appear
• Keyboard accessible with focus management and screen reader announcements
• Under 5 KB gzipped with zero external dependencies
• Dark mode support with automatic and manual theme switching

Comparison with Similar Tools

• react-hot-toast — similar API but Sonner has smoother stacking animations and promise tracking
• react-toastify — feature-rich but heavier; Sonner is lighter with more polished defaults
• Radix Toast — unstyled primitive; Sonner is fully styled and ready to use
• Chakra UI Toast — tied to Chakra; Sonner works with any styling approach
• Notistack — Material UI focused; Sonner is framework-agnostic with its own design

FAQ

Q: Can I customize the toast appearance? A: Yes, you can override styles via CSS, pass custom className, or render entirely custom JSX inside toasts.

Q: Does Sonner work with Next.js Server Components? A: The Toaster component needs to be in a client component. The toast() function can be called from anywhere including server action callbacks.

Q: How many toasts can stack at once? A: By default 3 are visible with older ones collapsed. This is configurable via the visibleToasts prop.

Q: Is there Vue or Svelte support? A: Community ports exist. The official package targets React, but the API pattern has inspired similar libraries for other frameworks.

Sources

• https://github.com/emilkowalski/sonner
• https://sonner.emilkowal.ski