Sonner

Purpose and Scope

Sonner is the toast notification entry in the component catalog: an opinionated React toast component that gives an application a single notification surface while leaving the implementation in the user project. The component docs identify it as a component page, describe it as an opinionated toast component for React, and link readers to the upstream Sonner API reference maintained outside this repository. In shadcn/ui terms, the important workflow is not importing a black-box package alone; it is adding a local Toaster wrapper and then triggering notifications from application code with the Sonner toast API.

Sources: apps/v4/content/docs/components/aria/sonner.mdx

The Sonner page is especially useful for readers who already understand the component-copying model but need to know where the toast host belongs. The docs place Toaster in the root layout body, alongside the main application content, so toasts can be rendered from anywhere below that layout. That placement makes the component feel global without requiring every page or feature to render its own toast container. It also keeps the app code simple: install or copy the component once, mount the host once, then call the toast function where the user action happens.

Sources: apps/v4/content/docs/components/aria/sonner.mdx

Relevant Source Files

• apps/v4/content/docs/components/aria/sonner.mdx — Defines the Sonner component documentation page, including metadata, CLI and manual installation steps, Toaster layout examples, toast usage, preview sections, position guidance, and the external API reference link.
• apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx — Provides CLI context for the modern add and init workflow, including component dependencies, framework support, remote registry installs, aliases, better error handling, and monorepo support.
• apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx — Explains resolve-anywhere registry installation behavior, which matters when component files and imports are placed outside a fixed structure.
• apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx — Frames the Base UI and Radix choice, visual styles, and code-transforming customization model that influence how catalog components such as Sonner are generated.
• apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx — Documents applying a preset to an existing project, reinstalling existing components, and updating theme, colors, CSS variables, fonts, and icons.
• apps/v4/content/docs/changelog/2026-05-shadcn-eject.mdx — Explains shared Tailwind utilities, global CSS imports, RTL-related fixes, and the eject command for inlining the shared CSS dependency.

Installation Flow

The recommended installation path is the CLI path. The page’s command tab tells the reader to run the add command for Sonner, then add the Toaster component to the root layout. That sequence matters because the command brings the component source into the project, while the layout change wires the rendered toast area into the app shell. The changelog for the rewritten CLI explains why this is the normal path: the CLI can install components, themes, hooks, utilities, and dependencies, and components can ship their own dependency and configuration requirements instead of relying on a manual checklist.

Sources: apps/v4/content/docs/components/aria/sonner.mdx, apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

npx shadcn@latest add sonner

After the component has been added, mount Toaster in the layout that wraps the pages that should be able to emit notifications. The docs example imports Toaster from the project’s UI component alias and renders it inside the document body. The example shows main content and Toaster as siblings, which is the key pattern to preserve even if an application has additional providers, headers, route shells, or theme wrappers. In a Next.js-style root layout, keep the host stable across route changes so existing toasts are not unintentionally destroyed by page-level remounts.

Sources: apps/v4/content/docs/components/aria/sonner.mdx

import { Toaster } from "@/components/ui/sonner"
 
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head />
      <body>
        <main>{children}</main>
        <Toaster />
      </body>
    </html>
  )
}

Manual Installation and Project Fit

The manual tab exists for projects that do not want to use the CLI for this component or that need to inspect the wrapper before adding it. It instructs readers to install the Sonner package and next-themes, then copy the component source into the project as components/ui/sonner.tsx. The dependency list is a signal that the local wrapper is not only a re-export; it participates in the project’s theme behavior while still delegating toast behavior to the Sonner library. The page then repeats the same layout mounting step, because manual installation does not remove the need for a global toast host.

Sources: apps/v4/content/docs/components/aria/sonner.mdx

npm install sonner next-themes

import { Toaster } from "@/components/ui/sonner"
 
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head />
      <body>
        <Toaster />
        <main>{children}</main>
      </body>
    </html>
  )
}

When adapting the manual example, align the import alias with the project’s components configuration rather than copying it mechanically. The CLI changelog for the new init workflow calls out aliases for components, utilities, UI, library code, and hooks, and notes that projects using a different alias prefix should replace the default prefix accordingly. That guidance applies directly to Sonner because the docs import Toaster through the UI alias. In a monorepo or nonstandard app, the same component can still be used, but the import should resolve through the local project’s configured component path.

Sources: apps/v4/content/docs/components/aria/sonner.mdx, apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

Usage and Runtime Behavior

Once Toaster is mounted, feature code imports the toast function from the Sonner package and calls it when an event should be announced. The docs deliberately keep the first example small: import toast, then call it with a message such as Event has been created. This separation is the public mental model for the component. Toaster is the mounted renderer, while toast is the imperative trigger used in action handlers, mutation callbacks, form submissions, or other application events. If a toast call appears to do nothing, first verify that the host component is mounted in an active layout.

Sources: apps/v4/content/docs/components/aria/sonner.mdx

import { toast } from "sonner"

toast("Event has been created.")

The component page groups additional examples into Types, Description, and Position sections. Types and Description are represented by component previews, so readers should treat them as supported usage demonstrations rather than separate installation modes. The Position section gives one concrete API hint: use the position prop to change where the toast appears. The detailed prop contract remains delegated to the upstream Sonner API reference linked from the page. In shadcn/ui documentation, this division is intentional: the local page teaches installation and integration, while upstream Sonner documentation remains the source for the full toast option matrix.

Sources: apps/v4/content/docs/components/aria/sonner.mdx

System-to-Code Mapping

Sonner sits at the intersection of the component catalog and the registry-based CLI workflow. The docs page supplies the reader-facing recipe, while the CLI changelogs explain why the recipe remains flexible across frameworks and project layouts. The 2024 CLI rewrite states that components can ship their own dependencies, that init updates existing Tailwind files instead of overwriting them, and that remote components can be installed by URL. For Sonner, the practical takeaway is that the add workflow should be preferred when possible because it can carry more project-aware behavior than simply copying a snippet from a documentation page.

Sources: apps/v4/content/docs/components/aria/sonner.mdx, apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

The later changelog entries explain how Sonner fits into the newer customizable component system. Resolve-anywhere support means registry installs are not constrained to a fixed file tree and can perform multi-pass import and alias resolution. The create announcement says users can pick a component library, icons, base color, theme, and fonts, and that configuration can rewrite component code to match the setup. The apply command extends that model to existing projects by reinstalling existing components while updating theme values, variables, fonts, icons, and colors. These changes make Sonner a generated local component that can follow the project’s chosen style system rather than a frozen shared package.

Sources: apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx, apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx, apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx

The eject changelog adds one more operational detail for projects that care about dependency boundaries. Shared Tailwind utilities were introduced for behavior used across Radix and Base UI implementations, including custom variants and utilities, and the init flow imports shadcn/tailwind.css into global CSS. The eject command can inline that shared CSS and remove the shadcn dependency. Sonner’s docs do not require a special eject step, but teams standardizing component ownership should know that the surrounding shadcn styling infrastructure can also be made local when they want their copied component library to avoid that package dependency.

Sources: apps/v4/content/docs/changelog/2026-05-shadcn-eject.mdx

Compact Reference

Next Steps

Start with the CLI command unless you have a reason to copy the component manually. After adding Sonner, place Toaster in the highest layout that should own notifications, then trigger a simple toast from a button, form submission, or mutation success path to verify that rendering works. If the import alias differs from the documentation example, update it to match the project’s configuration. For broader context, read the CLI page for add behavior, the components overview for catalog conventions, and the theming or Base Components pages when adapting generated component code to a custom visual style.