Overlay

Toast

Transient notification stack. Wrap the app in ToastProvider and fire toasts imperatively with useToast(); danger toasts announce assertively, others politely. Hovering pauses the auto-dismiss timer.

Import

import { ToastProvider, useToast, Toast } from "@zephora/react";

Examples

Firing toasts

`useToast()` returns `toast(options)` which shows a toast and returns its id. `duration: null` keeps a toast until closed.

function App() {
  return (
    <ToastProvider>
      <Buttons />
    </ToastProvider>
  );
}

function Buttons() {
  const { toast } = useToast();
  return (
    <>
      <Button
        onClick={() =>
          toast({ title: "Saved", description: "Your changes are live.", status: "success" })
        }
      >
        Success toast
      </Button>
      <Button
        variant="outline"
        onClick={() => toast({ title: "Connection lost", status: "danger", duration: null })}
      >
        Persistent danger toast
      </Button>
    </>
  );
}

Action and dismiss

Toasts can carry one action; `dismiss(id)` removes a toast programmatically.

function ArchiveButton() {
  const { toast, dismiss } = useToast();
  return (
    <Button
      variant="soft"
      onClick={() => {
        const id = toast({
          title: "Message archived",
          status: "info",
          duration: 8000,
          action: { label: "Undo", onClick: () => dismiss(id) },
        });
      }}
    >
      Archive with undo
    </Button>
  );
}

Promise flow

`toast.promise(promise, { loading, success, error })` shows a sticky loading toast, then updates the SAME toast when the promise settles. `success`/`error` accept content or a function of the result. For manual control use `update(id, options)` and `dismissAll()`.

function UploadButton() {
  const { toast } = useToast();
  return (
    <Button
      onClick={() => {
        const upload = new Promise<string>((resolve) =>
          window.setTimeout(() => resolve("report.pdf"), 2000)
        );
        void toast.promise(upload, {
          loading: "Uploading report…",
          success: (name) => ({
            title: "Uploaded",
            description: `${name} is ready.`,
            status: "success",
          }),
          error: "Upload failed",
        });
      }}
    >
      Upload with toast.promise
    </Button>
  );
}

Standalone Toast card

The presentational `<Toast>` can be rendered inline — ToastProvider uses it internally.

Build passed

All 214 tests green.

<Toast
  title="Build passed"
  description="All 214 tests green."
  status="success"
  onClose={() => console.log("closed")}
/>

API

ToastProvider props

Prop	Type	Default	Description
`position`	`"top-start" \| "top" \| "top-end" \| "bottom-start" \| "bottom" \| "bottom-end"`	`"bottom-end"`	Viewport corner where toasts stack.
`maxToasts`	`number`	—	Maximum number of toasts visible at once; further toasts queue (FIFO) and appear as soon as a slot frees up.
`unstyled`	`boolean`	`false`	Headless mode — skips Zephora styling.

useToast() props

Prop	Type	Default	Description
`toast(options)`	`(options: ToastOptions) => string`	—	Shows a toast and returns its id. Also exposes toast.promise().
`update(id, options)`	`(id: string, options: Partial<ToastOptions>) => void`	—	Re-renders an existing toast in place; restarts the timer if duration is provided.
`dismiss(id)`	`(id: string) => void`	—	Removes the toast with the given id (plays the exit animation).
`dismissAll()`	`() => void`	—	Removes every visible toast and clears the pending queue.
`promise(promise, options)`	`<T>(promise: Promise<T>, options: { loading, success, error }) => Promise<T>`	—	Shows a sticky loading toast, then updates the same toast to a success/error message when the promise settles. Returns the promise.

useToast() → toast(options) props

Prop	Type	Default	Description
`title` *	`ReactNode`	—	Main line of the toast.
`description`	`ReactNode`	—	Supporting text under the title.
`status`	`"info" \| "success" \| "warning" \| "danger"`	`"info"`	Semantic tone; danger announces assertively.
`duration`	`number \| null`	`5000`	Auto-dismiss delay in ms; null keeps the toast until closed.
`action`	`{ label: string; onClick: () => void }`	—	Single action button rendered next to the content.
`icon`	`ReactNode \| null`	—	Leading icon. Defaults to the built-in status icon; pass null to render no icon at all.
`position`	`ToastPosition`	—	Viewport corner for this toast; falls back to the provider position.

Toast (standalone) props

Prop	Type	Default	Description
`title` *	`ReactNode`	—	Main line of the toast.
`description`	`ReactNode`	—	Supporting text under the title.
`status`	`"info" \| "success" \| "warning" \| "danger"`	`"info"`	Semantic tone.
`action`	`{ label: string; onClick: () => void }`	—	Single action button.
`duration`	`number \| null`	`null`	Auto-dismiss delay in ms (requires onClose); null disables the timer. The timer pauses on hover.
`onClose`	`() => void`	—	Renders the close button and is called on close / when the timer fires.
`unstyled`	`boolean`	`false`	Headless mode.