Sonner (Toast)

Ephemeral toast notifications via Sonner. Render <Toaster /> once at app root, then call toast() anywhere.

Installation

pnpm

pnpm dlx @hex-core/cli add sonner

Success toast with action

Actionable confirmation — surface an Undo affordance alongside the success message

tsx

<Button
  onClick={() =>
    toast.success("Project archived", {
      description: "It will be hidden from your dashboard.",
      action: {
        label: "Undo",
        onClick: () => restoreProject(),
      },
    })
  }
>
  Archive project
</Button>

Loading → resolved/rejected

toast.promise drives one toast through three states (loading, success, error)

tsx

<Button
  onClick={() =>
    toast.promise(saveProject(), {
      loading: "Saving project…",
      success: (data) => `Saved "${data.name}"`,
      error: (err) => `Failed to save: ${err.message}`,
    })
  }
>
  Save project
</Button>

API Reference

Prop	Type	Default	Description
`position`	`"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"`	bottom-right	Where toasts appear on screen
`richColors`	`boolean`	false	Enable success/error/warning color variants via toast.success/error/warning
`closeButton`	`boolean`	false	Show a close button on each toast
`theme`	`"light" \| "dark" \| "system"`	system	Visual theme

AI Guidance

When to use

Use for transient feedback: save confirmations, error messages, background task completion. Pairs well with mutation handlers (onSuccess/onError).

When not to use

Don't use for persistent info (use Alert). Don't use for destructive confirmations (use AlertDialog). Don't use for critical errors that block user workflow.

Common mistakes

Rendering multiple <Toaster /> components (one is enough)
Calling toast() during server rendering (must be client-side)
Using toast for messages the user needs to re-read (they auto-dismiss)

Accessibility

Sonner handles aria-live='polite' on the toast region so screen readers announce new toasts. Critical messages should still use Alert/AlertDialog for persistent visibility.

Related components

Token budget: 450

Verified against @hex-core/components@1.12.0

Edit this page on GitHub