Skip to content
Nexus Application Design nadesign

Sonner (Toast)

The toast primitive — wraps the sonner library. Mount <Toaster /> once at the app root and call toast(...) from anywhere.

import from "@na/ui/components/sonner" ▶ Open in Storybook packages/ui/src/components/sonner.tsx

When to use

  • After-action feedback (“Saved”, “Published”, “Deleted — Undo”).
  • Async failures the user can act on (“Couldn’t save — Retry”).
  • Background events that the user might want to know about but doesn’t need to interrupt them.

Don’t use Toast for: required confirmations (AlertDialog), persistent in-page messages (Alert), or form-field errors (FormError, FormMessage).

Showcase

 
import { Toaster } from '@na/ui/components/sonner';
import { toast } from 'sonner';


// Mount once near the app root
<Toaster richColors closeButton />


toast('Saved.');                                   // default
toast.success('Agent published.');                 // success
toast.error("Couldn't save: name is taken.");      // error
const id = toast.loading('Publishing…');           // loading → resolve
toast.success('Published.', { id });
toast('Item removed.', {                            // with action
  action: { label: 'Undo', onClick: () => api.restore() },
});

API

Toaster (mount once)

Prop Type Default Description
position "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center" "bottom-right" Where toasts appear.
richColors boolean false Tints toasts by tone (success / error / info / warning).
closeButton boolean false Show the manual-close X.
duration number 4000 Default visible duration in ms.
theme "light" | "dark" | "system" "system" Theme override.

toast(...) and helpers

toast(message, options), toast.success, toast.error, toast.warning, toast.info, toast.loading, toast.promise(p, { loading, success, error }). Pass { id } to update an existing toast (loading → success / error).

Design guidelines

✓ Do

  • Pair destructive actions with a Toast that includes an Undo. Friendlier than a confirm-first modal.
  • Use toast.loading + id for async operations — replace the loading toast on resolution.
  • Lead with the verb in past tense: "Saved.", "Deleted.", "Published v3."

✗ Don't

  • Toast routine save success on every keystroke. Once on save is enough.
  • Use toast.error for recoverable validation. The form is the right home.
  • Stack 5 toasts on top of each other. Sonner caps display, but the smell is upstream.

Accessibility

  • Toasts render with role="status" (info) or role="alert" (error) — screen readers announce them.
  • Auto-dismiss respects prefers-reduced-motion.
  • closeButton exposes an explicit close action for keyboard users.

▶ Open Sonner stories in Storybook