# Shadcn Sonner (Toast)
> Free shadcn/ui toast component for React — built on Sonner. Success/error/info/warning, descriptions, action buttons, promise (loading→success/error), rich colors, and fully custom toasts. The toast that replaced the deprecated shadcn Toast.
Source: https://designrevision.com/components/sonner
The **Shadcn Sonner** is the toast — built on **Sonner**, the toast library by Emil Kowalski. shadcn **deprecated its old Toast** component in favour of Sonner, so this is the current, recommended way to show toasts. The examples below cover the whole `toast()` API: types, descriptions, actions, promises, rich colors, and custom toasts.
## Built on Sonner
The shadcn layer is a thin `` wrapper over Sonner that themes it to your design tokens (via CSS variables) and follows your light/dark theme. Install it:
```bash
npm install sonner
```
(The shadcn component also pulls in `next-themes` for theme detection; it falls back to the system theme if you don't use a theme provider.)
## Mount the Toaster once
Sonner is **API-driven**: you mount one `` near the **root** of your app — typically in `app/layout.tsx` — and then call `toast()` from anywhere:
```tsx
// app/layout.tsx
{children}
```
The examples on this page each render their own `Toaster` so they work standalone, but your app needs only one.
## The toast() API
Call `toast` from `"sonner"`:
- **Basic** — `toast("Event has been created", { description: "…" })`.
- **Types** — `toast.success(...)`, `toast.error(...)`, `toast.info(...)`, `toast.warning(...)` (the Types example).
- **Action** — `toast("Moved to trash", { action: { label: "Undo", onClick } })` (the With action example).
- **Promise** — `toast.promise(p, { loading, success, error })` swaps a loading toast for success or error when the promise settles (the Promise example).
- **Custom** — `toast.custom((id) => )` for a fully custom toast (the Custom JSX example).
## Configuring the Toaster
Options that affect the **whole stack** go on ``, not individual toasts:
```tsx
```
`position` moves the stack, `richColors` gives each type a colored surface, `closeButton` adds an X, and `duration` controls how long toasts persist. The Rich colors & close example shows `richColors` + `closeButton`.
## Migrating from the old Toast
If you used shadcn's old `useToast()` / `` API, Sonner replaces it: drop the `` and `` from `@/components/ui/toast`, mount the Sonner ``, and replace `toast({ title, description })` calls with `toast(title, { description })`. It's less boilerplate and the same idea.
## Accessibility & theming
Sonner manages focus, screen-reader announcements (toasts are announced politely), and keyboard dismissal. Because it's a notification surface, keep messages short and don't put the only copy of critical information in a toast. The toast reads your design tokens — the wrapper maps Sonner's `--normal-bg` / `--normal-text` / `--normal-border` to `--popover` / `--popover-foreground` / `--border` — so it follows your theme, including dark mode, with no overrides.
## Installation
### sonner
**Install:**
```bash
npx shadcn@latest add @designrevision/sonner
```
**Dependencies:** sonner, next-themes, utils
**Usage & accessibility:** The shadcn toast — a wrapper over Sonner (the toast library by emilkowalski), themed to your design tokens via CSS vars. It is API-driven: mount once near the root of your app, then call toast(), toast.success(), toast.error(), toast.promise(), or toast.custom() from anywhere. Toaster props (position, richColors, closeButton, duration) configure the stack. Needs next-themes for theme detection; it falls back to "system" without a ThemeProvider.
```tsx
// components/ui/sonner.tsx
"use client"
import { useTheme } from "next-themes"
import { Toaster as Sonner, ToasterProps } from "sonner"
const Toaster = ({ ...props }: ToasterProps) => {
const { theme = "system" } = useTheme()
return (
)
}
export { Toaster }
```
## Examples
### Sonner
The canonical toast — a button that calls `toast()` with a title and a description.
**Install:**
```bash
npx shadcn@latest add @designrevision/sonner-demo-01
```
**Dependencies:** sonner, button
```tsx
// components/ui/sonner-demo-01.tsx
"use client"
import { toast } from "sonner"
import { Button } from "@/components/ui/button"
import { Toaster } from "@/components/ui/sonner"
export default function SonnerDemo01() {
return (
{/* Mount once near the root of your app — shown here per example. */}
)
}
```
---
### Types
Success, error, info, and warning toasts via `toast.success` / `.error` / `.info` / `.warning`.
**Install:**
```bash
npx shadcn@latest add @designrevision/sonner-types-01
```
**Dependencies:** sonner, button
```tsx
// components/ui/sonner-types-01.tsx
"use client"
import { toast } from "sonner"
import { Button } from "@/components/ui/button"
import { Toaster } from "@/components/ui/sonner"
export default function SonnerTypes01() {
return (
)
}
```
---
### With description
A toast with a title and a secondary description line.
**Install:**
```bash
npx shadcn@latest add @designrevision/sonner-description-01
```
**Dependencies:** sonner, button
```tsx
// components/ui/sonner-description-01.tsx
"use client"
import { toast } from "sonner"
import { Button } from "@/components/ui/button"
import { Toaster } from "@/components/ui/sonner"
export default function SonnerDescription01() {
return (
)
}
```
---
### With action
A toast with an **Undo** action button and a dismiss — the classic undo pattern.
**Install:**
```bash
npx shadcn@latest add @designrevision/sonner-action-01
```
**Dependencies:** sonner, button
```tsx
// components/ui/sonner-action-01.tsx
"use client"
import { toast } from "sonner"
import { Button } from "@/components/ui/button"
import { Toaster } from "@/components/ui/sonner"
export default function SonnerAction01() {
return (
)
}
```
---
### Promise
`toast.promise` ties a toast to an async request — loading, then success or error.
**Install:**
```bash
npx shadcn@latest add @designrevision/sonner-promise-01
```
**Dependencies:** sonner, button
```tsx
// components/ui/sonner-promise-01.tsx
"use client"
import { toast } from "sonner"
import { Button } from "@/components/ui/button"
import { Toaster } from "@/components/ui/sonner"
function uploadFile() {
return new Promise<{ name: string }>((resolve, reject) => {
setTimeout(() => {
if (Math.random() > 0.3) {
resolve({ name: "report.pdf" })
} else {
reject(new Error("Network error"))
}
}, 1500)
})
}
export default function SonnerPromise01() {
return (
)
}
```
---
### Rich colors & close
A `` — colored type surfaces with a close button.
**Install:**
```bash
npx shadcn@latest add @designrevision/sonner-rich-01
```
**Dependencies:** sonner, button
```tsx
// components/ui/sonner-rich-01.tsx
"use client"
import { toast } from "sonner"
import { Button } from "@/components/ui/button"
import { Toaster } from "@/components/ui/sonner"
export default function SonnerRich01() {
return (
{/* richColors gives each type a colored surface; closeButton adds an X. */}
)
}
```
---
### Custom JSX
`toast.custom` renders fully custom content — your own icon, layout, and dismiss button.
**Install:**
```bash
npx shadcn@latest add @designrevision/sonner-custom-01
```
**Dependencies:** lucide-react, sonner, button
```tsx
// components/ui/sonner-custom-01.tsx
"use client"
import { CheckCircle2Icon } from "lucide-react"
import { toast } from "sonner"
import { Button } from "@/components/ui/button"
import { Toaster } from "@/components/ui/sonner"
export default function SonnerCustom01() {
return (