Toast

Installation

pnpm dlx shadcn@latest add @spaceui/primitives-toast

Usage

Stacked Toasts

import { toastManager } from '@/components/ui/toast'

toastManager.add({
  title: 'Event has been created',
  description: 'Monday, January 3rd at 6:00pm',
})

By default, toasts appear in the bottom-right corner. You can change this by setting the position prop on the ToastProvider.

Allowed values: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right. For example:

<ToastProvider position="top-center">{children}</ToastProvider>

Deduplicated toasts (upsert)

Pass a stable id when calling toastManager.add. If a toast with that id already exists, Base UI updates it in place, refreshes the auto-dismiss timer, and increments updateKey. The styled toast replays a short re-notify animation on each update.

toastManager.add({
  id: 'save-status',
  title: 'Saved',
  description: 'Your draft was updated.',
})

Anchored Toasts

For toasts positioned relative to a specific element, use anchoredToastManager. The AnchoredToastProvider is typically added to your app layout (alongside ToastProvider), so you can use anchoredToastManager directly in your components:

anchoredToastManager.add({
  title: 'Copied!',
  positionerProps: {
    anchor: buttonRef.current,
  },
})

You can also style anchored toasts like tooltips by passing data: { tooltipStyle: true }. When using tooltip style, only the title is displayed (description and other content are ignored):

anchoredToastManager.add({
  title: 'Copied!',
  positionerProps: {
    anchor: buttonRef.current,
  },
  data: {
    tooltipStyle: true,
  },
})

API Reference

ToastProvider

Provider component for stacked toasts. Wraps Toast.Provider from Base UI.

AnchoredToastProvider

Provider component for toasts anchored to specific elements. Use with anchoredToastManager.

toastManager

Manager object for creating stacked toasts. Use toastManager.add() to show a toast. Pass the same id on a later add to update that toast in place (dedupe) instead of stacking a duplicate.

anchoredToastManager

Manager object for creating anchored toasts. Use anchoredToastManager.add() with positionerProps.anchor to show a toast anchored to an element. Repeated add calls with the same id update in place, same as stacked toasts.

ToastViewport

Viewport container for toasts. Styled wrapper for Toast.Viewport from Base UI.

Toast

Individual toast container. Styled wrapper for Toast.Root from Base UI.

ToastTitle

Title text for the toast. Styled wrapper for Toast.Title from Base UI.

ToastDescription

Description text for the toast. Styled wrapper for Toast.Description from Base UI.

ToastAction

Action button for the toast. Styled wrapper for Toast.Action from Base UI.

ToastClose

Close button for the toast. Styled wrapper for Toast.Close from Base UI.

Examples