Components

Toast

A notification stack for outcomes the user did not just watch happen

Import

import { Toaster, toast } from "@nyte-ai/ui/toast";

Toaster renders the stack and toast.add opens a notification in it. Keep form errors in the form.

Usage

Mount one Toaster near the app root.
Call toast.add anywhere, including outside React.
Set type to "success", "error", or "warning" for a status icon.
Adding with an existing id updates that toast and refreshes its timer.
Error toasts with a string title get a Copy error button. A string description joins the copied text on a new line.
Action buttons use actionProps. Call toast.close(id) in the handler to close the notification.
A single button sits beside the title. A description or a second button moves the buttons below the text.

Examples

<Button variant="outline" onClick={() => toast.add({ title: "Workspace saved" })}>
  Default
</Button>
<Button
  variant="outline"
  onClick={() =>
    toast.add({
      type: "success",
      title: "3 chats archived",
      id: "archive-demo",
      actionProps: {
        children: "Undo",
        onClick: () => {
          toast.close("archive-demo");
          toast.add({ title: "Chats restored" });
        },
      },
    })
  }
>
  Success
</Button>
<Button
  variant="outline"
  onClick={() =>
    toast.add({
      type: "error",
      title: "Could not reach the server",
      description: "The request timed out after 30 seconds.",
    })
  }
>
  Error
</Button>
<Toaster />

A toast that stays

const id = toast.add({
  type: "error",
  title: "Couldn't open folder",
  id: "workspace-open",
  timeout: 0,
  description: reason,
});

toast.close(id);

An action and undo

onClose runs for every close, including the timer and toast.close. Mark the action as undone before closing it.

let undone = false;

toast.add({
  type: "success",
  title: "3 chats archived",
  id: "archive",
  actionProps: {
    children: "Undo",
    onClick: () => {
      undone = true;
      restore();
      toast.close("archive");
    },
  },
  onClose: () => {
    if (!undone) commit();
  },
});

A pending operation

await toast.promise(save(), {
  loading: "Saving",
  success: "Saved",
  error: (cause: unknown) => (cause instanceof Error ? cause.message : "Couldn't save"),
});

Each state accepts a string or an options object. success and error also accept a function returning either. The returned promise resolves with the operation's result or rejects with its error.

Props

Toaster

Toaster accepts Base UI's Toast.Provider props except children. The stack sits at the bottom-right and uses the current color tokens.

Prop	Type	Default	Description
`timeout`	`number`	`5000`	Default auto-close milliseconds. `0` disables automatic dismissal.
`limit`	`number`	`3`	Visible toast limit. Older toasts are hidden rather than removed.
`toastManager`	`ToastManager`	`toast`	Manager whose notifications this stack renders.

toast

Call	Returns	Description
`toast.add(options)`	`string`	Opens a toast, or updates an existing id and refreshes its timer.
`toast.close(id?)`	`void`	Closes one toast, or all of them with no argument.
`toast.update(id, options)`	`void`	Updates a toast. Also accepts a function of the current toast.
`toast.promise(promise, { loading, success, error })`	`Promise<Value>`	Updates one toast through loading, success, and error.

Toast options

ToastOptions<Data> is exported for typing options passed to toast.add. toast.update accepts partial options without id.

Option	Type	Description
`title`	`ReactNode`	Notification title.
`type`	`string`	`"success"`, `"error"`, and `"warning"` render status icons.
`description`	`ReactNode`	Text below the title.
`id`	`string`	Generated when omitted. Reuse it to update the toast and refresh its timer.
`timeout`	`number`	Auto-close milliseconds. Defaults to the provider's timeout. `0` stays open.
`actionProps`	`ComponentPropsWithoutRef<"button">`	Action button props, including `children` and `onClick`.
`onClose`	`() => void`	Runs when the toast closes, whether by user, action handler, timer, or code.
`onRemove`	`() => void`	Runs after the closed toast's exit animation finishes.
`priority`	`"low" \| "high"`	Polite or urgent announcement. Defaults to `"low"`.
`data`	`Data`	Custom data associated with the toast.

Accessibility

The viewport is a region named "Notifications" with aria-live="polite".
priority: "high" announces a toast urgently without moving focus.
F6 focuses the notification stack. Hovering or focusing it pauses automatic dismissal.
Every close button is named "Dismiss notification". Every Copy button is named "Copy error", then "Copied" for a moment after copying.
Loading toasts have no timer but can still be closed.