Basel Standard / Docs

Sonner

Lightweight toast feedback with the repo's shared Swiss wrapper for typography, actions, and theme alignment.

This page documents the repo wrapper around sonner. The wrapper exposes a single Toaster component styled to match the rest of the system, while toast creation still comes from the sonner package itself. Use it for brief feedback that should confirm an action without interrupting the current page.

Installation

Install

Purchase access, then open /account/install to issue a registry token.

Usage

import { Toaster } from "@/components/ui/sonner"
import { toast } from "sonner"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <Toaster />
    </>
  )
}

<Button
  onClick={() =>
    toast.success("Release brief exported.", {
      description: "A copy was sent to the review inbox.",
    })
  }
>
  Export brief
</Button>

Why This Primitive Exists

Many actions need acknowledgement, not a modal. Sonner gives those moments a consistent surface for confirmations, warnings, and reversible actions while letting the user keep moving through the current workflow.

Use it for lightweight status feedback after an action completes or is queued.
Prefer it when the message is brief and the page should remain interactive.
Avoid it for validation errors or decisions that the user must resolve before continuing.

Examples

Basic Feedback

Use success or neutral notices for brief confirmation that the system accepted the action.

toast.success("Coverage note sent.", {
  description: "The revised proof has been queued for stakeholder review.",
})

Action Toasts

Action and cancel buttons are useful when the next step is small, reversible, and still secondary to the main workflow.

toast("Publish queued for 09:00.", {
  action: { label: "Undo", onClick: () => undefined },
  cancel: { label: "Dismiss", onClick: () => undefined },
})

In Context

Toasts work best when they stay close to product work such as exports, queue changes, approvals, and publish actions. They should confirm the result, not replace the workflow itself.

Workflow feedback

Use sonner for lightweight confirmation that should not block the current task.

The toast stays useful when the message is brief, the next action is clear, and the page should remain active underneath.

toast("Missing subscriber copy.", {
  description: "Escalate with inline validation if the user must fix the issue immediately.",
})

Guidance

Keep The Message Short

Lead with the result: exported, queued, failed, approved.
Use the description only for one clarifying line.
If the user needs a paragraph to understand the notice, it should not be a toast.

Do Not Hide Required Decisions In A Toast

Use toasts for confirmation and lightweight follow-up actions.
Use dialogs, inline validation, or page-level notices when the user must stop and resolve something.
If the action is destructive, the confirmation belongs before the action, not only after it.

Mount One Shared `Toaster`

Render Toaster once near the app root.
Trigger notices from anywhere with toast(...), toast.success(...), or the other sonner helpers.
Keep the wrapper styling consistent instead of mounting ad hoc custom toaster variants per page.

API Reference

`Toaster`

Toaster is the repo's wrapper around sonner's Toaster component and accepts React.ComponentProps<typeof Sonner>.

Prop	Type	Default	Notes
`theme`	sonner theme prop	derived from `next-themes`	The wrapper reads the current theme and passes it through.
`className`	`string`	`"toaster group"`	Adds the shared wrapper classes.
`toastOptions`	sonner toast options	repo defaults applied	You can extend the defaults if needed.

Built-In Wrapper Behavior

Area	Detail
Success icon	Replaced with the repo's square-stroked success mark.
Typography	Titles, descriptions, and actions use the shared uppercase and body styles.
Surface	Toasts render with the same border, background, and no-shadow treatment used across the Swiss system.
Actions	Action and cancel buttons inherit the repo's restrained button styling.

Toast creation functions such as toast, toast.success, toast.error, and toast.promise still come from the sonner package directly. This file only wraps the mounted toaster surface.

Previous: Slider Next: Spinner