Action Toast

"use client"
import {
  ActionToast,

The ActionToast is the surface of a toast that asks for a next step: money received with a view action, a frozen card with undo, a delayed send you can cancel, or a statement being prepared. It sits on the inverted primary fill and is built from parts, so you render it inside toast.custom() from the Sonner toaster or in any other live region. Use the plain toaster for short confirmations without actions, and ActionToast once the toast carries an action, a deadline or progress.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @dots/action-toast
Copy

Usage#

Copyimport {
  ActionToast,
  ActionToastAction,
  ActionToastActions,
  ActionToastContent,
  ActionToastDescription,
  ActionToastMedia,
  ActionToastTitle,
} from "@/components/ui/action-toast"
import { SnowflakeIcon } from "lucide-react"
import { toast } from "sonner"

Copytoast.custom(
  (id) => (
    <ActionToast>
      <ActionToastMedia>
        <SnowflakeIcon />
      </ActionToastMedia>
      <ActionToastContent>
        <ActionToastTitle>Card frozen</ActionToastTitle>
      </ActionToastContent>
      <ActionToastActions>
        <ActionToastAction
          onPress={() => {
            unfreezeCard()
            toast.dismiss(id)
          }}
        >
          Undo
        </ActionToastAction>
      </ActionToastActions>
    </ActionToast>
  ),
  { unstyled: true }
)

Composition#

Use the following composition to build an action toast:

CopyActionToast
├── ActionToastMedia or ActionToastCountdown
├── ActionToastContent
│   ├── ActionToastTitle
│   └── ActionToastDescription
├── ActionToastActions
│   └── ActionToastAction
└── ActionToastProgress or ActionToastSteps

Features#

• A pill for one line and a tile once there is a description, progress or a second row of actions
• Media as an avatar, a bare icon, a round glyph or a spinner
• One action at the end of the row, or two equal actions on their own row
• An undo countdown ring that pauses while a pointer is over the toast or focus is inside it
• Known progress on the kit Progress, and step segments for batches with failed steps
• A destructive tone that fills only the glyph, never the whole toast

In a toaster#

Render the toast with toast.custom() and pass unstyled: true, so ActionToast is the only surface. When a countdown owns the lifetime, set duration: Infinity and dismiss the toast in onComplete.

"use client"

import { toast } from "sonner"

Undo#

Put an ActionToastCountdown in place of the media for an action that commits after a short window. Commit the action in onComplete, and change the countdown's key to start over. Say the deadline once in the description instead of announcing every second.

"use client"

import * as React from "react"

Delayed send#

The same countdown works for a payment that leaves after a few seconds. Pass isPaused to stop the clock, for example while the payment is being reviewed, and say so in the description.

"use client"

import * as React from "react"

Progress#

Add ActionToastProgress under the text for known progress, and set isPending on ActionToastMedia for work of unknown length.

"use client"

import * as React from "react"

Steps#

Use ActionToastSteps for an operation made of separate steps, such as a batch of payouts. Each step is "done", "failed" or "pending".

"use client"
import {
  ActionToast,

Two actions#

Two actions in ActionToastActions move to their own full-width row. Use emphasis="quiet" for the safer choice and keep one solid action.

"use client"
import {
  ActionToast,

Error#

Set tone="destructive" on a glyph media for a failed payment or a security event, and say what failed in the description.

"use client"
import {
  ActionToast,

Accessibility#

ActionToastAction renders the kit Button, built on React Aria, with press, focus and pending handling. ActionToastProgress and ActionToastSteps render a React Aria ProgressBar, so their values are read on demand, not announced. ActionToastSteps reads its value as "7 of 12" or "7 of 12, 2 failed".

Live region#

ActionToast sets no role, because a toaster already announces what it renders. When you render it on its own, pass role="status", or role="alert" for errors and security events, or place it inside an element with that role.

Copy<ActionToast role="alert">{/* ... */}</ActionToast>

Name progress#

ActionToastProgress and ActionToastSteps have no visible label, so both require an aria-label or aria-labelledby.

Label icon-only actions#

Give an ActionToastAction with size="icon" an aria-label, such as "Cancel statement".

Time to act#

The countdown pauses while a pointer is over the toast or focus is inside it. It is hidden from assistive technology; put the deadline in the description, such as "undo within 5 seconds".

Media#

ActionToastMedia is decorative by default because the title says what happened. Pass aria-hidden={false} when the media carries meaning of its own.

API Reference#

ActionToast#

The toast surface. Renders a <div>.

ActionToastMedia#

What the toast is about. Renders a <span>.

ActionToastContent#

Wraps the title and description.

ActionToastTitle#

What happened, such as "Template deleted".

ActionToastDescription#

The object or the detail. Its presence turns an auto toast into a tile.

ActionToastActions#

Holds one or two actions. Two actions move to their own full-width row.

ActionToastAction#

An action on the inverted surface. Renders a Button and accepts its props except variant and size.

ActionToastCountdown#

A ring that empties over duration, with the whole seconds left in the middle.

ActionToastProgress#

Known progress as a full-width bar. Renders the kit Progress and accepts its props.

ActionToastSteps#

One segment per step. Renders a React Aria ProgressBar.