sonner

An opinionated toast component for React.

weekly downloads9.9M

versionv2.0.7

licenseMIT

categoryfrontend

reactnotificationstoastsnackbarmessage

Overview

Sonner is a lightweight toast notification library for React that emphasizes developer experience through a minimalist API and smart defaults. Created by Emil Kowalski, it provides a single global toast function and pre-configured component that handles positioning, animations, accessibility, and mobile gestures without requiring extensive setup. Unlike traditional notification libraries that demand provider wrappers and verbose configuration, Sonner follows an opinionated approach where you render one <Toaster /> component and call toast() anywhere in your application.

The library excels at handling asynchronous operations through its toast.promise() method, which automatically transitions between loading, success, and error states based on promise resolution. This makes it particularly effective for form submissions, API calls, and file uploads where users need real-time feedback without blocking interactions. With 9.9 million weekly downloads, Sonner has become the de facto choice for modern React frameworks like Next.js and is integrated into popular component libraries including shadcn/ui and Supabase's design system.

Sonner prioritizes accessibility with built-in ARIA attributes, keyboard navigation, and screen reader support. It supports rich content including custom JSX, action buttons for undo workflows, and configurable durations. The library's small bundle size and tree-shakeable design ensure minimal performance impact while delivering smooth animations and gesture controls on mobile devices. For teams building production applications that need reliable user feedback without the overhead of complex notification systems, Sonner provides the right balance of functionality and simplicity.

Quick Start

typescript

import { Toaster, toast } from 'sonner';
import { useState } from 'react';

function App() {
  return (
    <>
      <Toaster position="top-right" expand={false} richColors />
      <NotificationDemo />
    </>
  );
}

function NotificationDemo() {
  const [data, setData] = useState(null);

  const handleAsyncAction = () => {
    const promise = fetch('https://api.github.com/users/github')
      .then(res => res.json());

    toast.promise(promise, {
      loading: 'Fetching user data...',
      success: (userData) => {
        setData(userData);
        return `Loaded ${userData.name}`;
      },
      error: 'Failed to load user'
    });
  };

  const handleUndo = () => {
    const toastId = toast('Item deleted', {
      action: {
        label: 'Undo',
        onClick: () => {
          toast.success('Deletion cancelled', { id: toastId });
        }
      },
      duration: 5000
    });
  };

  return (
    <div>
      <button onClick={() => toast.success('Operation completed!')}>
        Show Success
      </button>
      <button onClick={handleAsyncAction}>
        Load Data with Promise
      </button>
      <button onClick={handleUndo}>
        Delete with Undo
      </button>
      <button onClick={() => toast.error('Something went wrong', {
        description: 'Please check your connection and try again'
      })}>
        Show Error
      </button>
    </div>
  );
}

Use Cases

Form submission feedback: Display loading toasts during API calls, automatically switch to success with server data, or show error messages with retry actions, all handled by toast.promise() without manual state management.

Undo destructive actions: Implement delete confirmations with action buttons that let users reverse operations within a time window, commonly used in email clients, task managers, or content management systems where accidental deletions need quick recovery options.

Multi-step workflow notifications: Track progress through complex operations like file uploads, batch processing, or multi-stage deployments by updating toast content programmatically using custom IDs to replace existing toasts instead of stacking new ones.

Real-time event updates: Show non-blocking notifications for background events like new messages, system alerts, or collaborative editing changes where users need awareness without interrupting their current task flow.

Authentication state changes: Communicate login success, session expiration warnings, or permission errors with appropriate styling (success/error variants) and optional navigation actions that redirect users after displaying feedback.

Pros & Cons

Pros

+Zero-config setup with single component and global API reduces boilerplate compared to context-based notification systems
+Native promise integration with automatic state transitions eliminates manual loading/error handling for async operations
+Built-in accessibility features including keyboard navigation, ARIA labels, and mobile gestures work without additional configuration
+Lightweight bundle size and opinionated defaults deliver production-ready notifications without extensive customization overhead
+Strong ecosystem integration with Next.js, shadcn/ui, and TypeScript support makes it ideal for modern React stacks

Cons

−Opinionated styling limits deep visual customization without CSS overrides or forking the component styles
−Global toast API pattern can complicate unit testing compared to component-scoped notification systems
−Limited animation customization options for teams requiring brand-specific motion design beyond provided presets
−No built-in notification queue prioritization or categorization for complex apps with multiple concurrent toast types
−Documentation lacks comprehensive migration guides for teams switching from established libraries like react-toastify

Alternatives

notistackv3.0.2

Highly customizable notification snackbars (toasts) that can be stacked on top of each other

frontendnotistackenqueueSnackbar

1.2M / week

react-hot-toastv2.6.0

Smoking hot React Notifications. Lightweight, customizable and beautiful by default.

frontendreactnotifications

2.8M / week

react-toastifyv11.0.5

React notification made easy

frontendreactnotification

3.0M / week

Comparisons

sonner vs react-hot-toast

frontend

Install

bash

npm install sonner

bash

pnpm add sonner

bash

bun add sonner

Overview

Quick Start

typescript

import { Toaster, toast } from 'sonner';
import { useState } from 'react';

function App() {
  return (
    <>
      <Toaster position="top-right" expand={false} richColors />
      <NotificationDemo />
    </>
  );
}

function NotificationDemo() {
  const [data, setData] = useState(null);

  const handleAsyncAction = () => {
    const promise = fetch('https://api.github.com/users/github')
      .then(res => res.json());

    toast.promise(promise, {
      loading: 'Fetching user data...',
      success: (userData) => {
        setData(userData);
        return `Loaded ${userData.name}`;
      },
      error: 'Failed to load user'
    });
  };

  const handleUndo = () => {
    const toastId = toast('Item deleted', {
      action: {
        label: 'Undo',
        onClick: () => {
          toast.success('Deletion cancelled', { id: toastId });
        }
      },
      duration: 5000
    });
  };

  return (
    <div>
      <button onClick={() => toast.success('Operation completed!')}>
        Show Success
      </button>
      <button onClick={handleAsyncAction}>
        Load Data with Promise
      </button>
      <button onClick={handleUndo}>
        Delete with Undo
      </button>
      <button onClick={() => toast.error('Something went wrong', {
        description: 'Please check your connection and try again'
      })}>
        Show Error
      </button>
    </div>
  );
}

Use Cases

Pros & Cons

Pros

+Zero-config setup with single component and global API reduces boilerplate compared to context-based notification systems
+Native promise integration with automatic state transitions eliminates manual loading/error handling for async operations
+Built-in accessibility features including keyboard navigation, ARIA labels, and mobile gestures work without additional configuration
+Lightweight bundle size and opinionated defaults deliver production-ready notifications without extensive customization overhead
+Strong ecosystem integration with Next.js, shadcn/ui, and TypeScript support makes it ideal for modern React stacks

Cons

−Opinionated styling limits deep visual customization without CSS overrides or forking the component styles
−Global toast API pattern can complicate unit testing compared to component-scoped notification systems
−Limited animation customization options for teams requiring brand-specific motion design beyond provided presets
−No built-in notification queue prioritization or categorization for complex apps with multiple concurrent toast types
−Documentation lacks comprehensive migration guides for teams switching from established libraries like react-toastify