Toast

A short message that appears for a few seconds and then goes away.

import { Button } from "@/components/ui/button"
import { toast } from "@/components/ui/toast"

export default function ToastDemo() {
  function showToast() {
    const id = toast.add({
      title: "Page published",
      description: "Monday, March 9 at 9:41 AM",
      actionProps: {
        children: "Undo",
        onClick() {
          toast.close(id)
        },
      },
    })
  }

  return (
    <Button variant="outline" onClick={showToast}>
      Show toast
    </Button>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/toast

Needs the arene setup first. Also adds Button, Spinner and Stack.

Usage

import { toast } from "@/components/ui/toast"
toast.add({
  title: "Page published",
  description: "Monday, March 9 at 9:41 AM",
})

toast is a manager created outside React, so it works from an event handler, a store or a fetch callback as well as from a component. toast.add returns the toast's id. Pass it to toast.close or toast.update.

Composition

Toaster renders all of this for you. Compose the parts yourself only when the built-in layout is not the one you need.

ToastProvider
└── ToastPortal
    └── ToastViewport            the fixed landmark the stack lives in
        └── Toast                one per toast in `useToastManager().toasts`
            └── ToastContent
                ├── ToastIcon
                ├── ToastTitle
                ├── ToastDescription
                ├── ToastAction
                └── ToastClose

Toasts stack. New toasts appear in front and older ones show below them at a smaller scale. The stack fans out while the pointer is over it or focus is inside it. A toast can be swiped down or to the right to dismiss it.

ToastTitle, ToastDescription and ToastAction read from the toast object and render nothing when it has no title, description or actionProps, so the built-in list needs no conditionals. Past the provider's limit, Base UI keeps the oldest toast mounted and marks it data-limited instead of removing it, so it can fade out in place.

Types

Set the type option to render a status icon. The built-in list recognises success, info, warning, error and loading.

import { Button } from "@/components/ui/button"
import { HStack } from "@/components/ui/stack"
import { toast } from "@/components/ui/toast"

export default function ToastTypes() {
  return (
    <HStack gap={2} wrap="wrap">
      <Button
        variant="outline"
        onClick={() => toast.add({ description: "Page has been published." })}
      >
        Default
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.add({ type: "success", description: "Page has been published." })}
      >
        Success
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({ type: "info", description: "Readers see the update within a minute." })
        }
      >
        Info
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({ type: "warning", description: "Pages cannot be scheduled before 8:00 AM." })
        }
      >
        Warning
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            type: "error",
            description: "The page could not be published.",
            priority: "high",
          })
        }
      >
        Error
      </Button>
    </HStack>
  )
}

Pass priority: "high" for a message a screen reader should announce at once. A screen reader announces everything else politely, after it finishes what it is reading.

Action

Pass button props with actionProps to render an action.

const id = toast.add({
  title: "Page published",
  actionProps: {
    children: "Undo",
    onClick() {
      toast.close(id)
    },
  },
})

Promise

Use toast.promise to update one toast as an asynchronous task moves through its loading, success and error states.

import { Button } from "@/components/ui/button"
import { toast } from "@/components/ui/toast"

export default function ToastPromise() {
  function showToast() {
    toast.promise(
      new Promise<{ name: string }>((resolve) => {
        window.setTimeout(() => resolve({ name: "Page" }), 2000)
      }),
      {
        loading: "Publishing page…",
        success: (data) => `${data.name} published.`,
        error: "Could not publish page.",
      },
    )
  }

  return (
    <Button variant="outline" onClick={showToast}>
      Publish page
    </Button>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Every part wraps the Base UI Toast part of the same name and accepts its props. See the Base UI reference for the manager options, anchored toasts and the primitive API. Each styled part also takes xstyle and className. Toast and ToastContent take style too. It is real inline CSS, merged over whatever the stack's state resolves to.

Toaster

Toaster takes the props of ToastProvider.

PropTypeDefault
timeoutnumber5000
limitnumber3
toastManagerToastManagertoast

A timeout of 0 keeps a toast up until it is closed. The timer pauses while the stack is fanned out.

toast

MethodSignature
add(options) => id
close(id?) => void
update(id, options) => void
promise(promise, { loading, success, error }) => promise

options takes title, description, type, timeout, priority, actionProps, onClose, onRemove and data. Adding a toast with an id that is already showing updates it in place and restarts its timer.

Toast

PropTypeDefault
toastToastObject—
swipeDirection"up" | "down" | "left" | "right" or an array of them["down", "right"]
styleCSSProperties—

Data attributes

AttributeOnEffect
data-slot="toast-viewport"the viewportThe fixed landmark; F6 moves focus into it
data-slot="toast"the rootThe box that stacks, slides and swipes
data-slot="toast-content"the contentThe padded row; fades while the toast is behind another
data-slot="toast-icon"the iconPresent only for a recognised type
data-typethe rootThe toast's type, as given
data-expandedroot, viewport, contentBase UI writes it while the stack is fanned out
data-limitedthe rootBase UI writes it past the provider's limit
data-swiping, data-swipe-directionthe rootBase UI writes them during a swipe
data-behindthe contentBase UI writes it on every toast but the front one
data-starting-style, data-ending-stylethe rootBase UI writes them while the toast animates