Toast

Pro

Where toasts appear: bottom right, newest at the bottom. Polite for successes, assertive for errors. Errors stay until dismissed, because a failure that vanishes on its own is easy to miss. Up to four show; past that the oldest toast that isn't an error goes, never a failure, so errors can stack beyond four, and the stack scrolls once it reaches the top of the screen. offset (or the --cd-toast-offset token) lifts it clear of something fixed at the bottom, such as a chat composer, so a toast never covers Send. If the focused control is under the stack anyway, the stack moves to the top. Screen readers hear each toast through two live regions that are on the page from the start, since a region added together with its text often isn't announced.

Markdown

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/toast

Brings in: locale, utils · npm: lucide-react@^1.67.0

Usage

TSX · The example above

"use client"

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

export default function Example() {
  return (
    <>
      {/* Mount one Toaster near the root of your app; call toast() from anywhere. */}
      <Toaster />
      <div className="flex flex-wrap gap-2">
        <Button
          variant="outline"
          onClick={() =>
            toast({
              tone: "success",
              title: "Migration applied on Staging",
              detail: "0042_add_region ran in 1.8s.",
              action: { label: "Open thread", onClick: () => {} },
            })
          }
        >
          Show a success
        </Button>
        <Button
          variant="outline"
          onClick={() => toast({ tone: "error", title: "The backfill stopped", detail: "The connection to Staging timed out after 40,000 rows." })}
        >
          Show an error
        </Button>
      </div>
    </>
  )
}

<Toaster>

Prop	Type	Default	Description
offset	`number \| string \| undefined`	—	Space to keep clear below the toasts, such as a composer's height: a number in px or a CSS length.
className	`string \| undefined`	—	Extra classes for the outer element.

Functions

dismissToast(id: number)

capToasts(list: T[], max = 4)

At most four on screen, but never by dropping a failure: the oldest toast that isn't an error goes first, and the newest always shows. Errors beyond four stay, since each one waits for someone to read it and dismiss it.

toast(input: ToastInput)

Show a toast. Returns its id. A run finishing in the background is the main use.

Strings

The fixed words, in English by default. Change any of them under toast in <LocaleProvider strings={{ … }}>; the table is exported as toastStrings.

Key	English
announcement	{title}. {detail}
dismiss	Dismiss

Types

ToastInput: { title: string detail?: string | undefined tone?: "success" | "error" | "info" | undefined action?: { label: string; onClick: () => void } | undefined /** ms; 0 keeps it until dismissed. Errors default to staying. */ duration?: number | undefined }