Toast

Imperative toast() API. Mount <Toaster /> once at the root, then fire one from anywhere.

loading never expires on its own - toast.promise settles it into success or danger.

Install Toast

1. New project? One command installs the package and wires everything - see Installation:

pnpm dlx zyncat-ui init

2. Import the component - it loads its own stylesheet:

import { Toast } from '@zyncat/ui/toast';

Usage

1import { toast, Toaster } from '@zyncat/ui/toast';
2 
3toast.success('Changes saved', { description: 'Updated across all workspaces.' });

Compose Toast in your application. No Tailwind or external styling library is required; every value resolves from Zyncat UI's token vocabulary.

Toast props

Toast

Prop	Type	Default	Description
`<Toaster />*`	`ToasterProps`	—	Mount once at the app root. Owns the viewport; toast() no-ops until it is mounted.
`Toaster position`	`'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'`	`'bottom-right'`	Corner the stack anchors to.
`Toaster duration`	`number`	`0`	Default auto-dismiss in ms for timed toasts; 0 keeps the per-tone defaults.
`Toaster visibleToasts`	`number`	`3`	How many cards stay visible before the rest recede behind.
`Toaster expand`	`boolean`	`false`	Start the stack fanned open instead of collapsed.
`Toaster gap, offset`	`number`	`0`	Px between cards and inset from the edge; 0 uses the token defaults.
`toast(msg, opts?)`	`(msg: string, opts?: ToastOptions) => string`	—	Show a neutral toast and return its id.
`toast.success(msg, opts?)`	`(msg: string, opts?: ToastOptions) => string`	—	Show a success toast; auto-dismisses after 5 s.
`toast.error(msg, opts?)`	`(msg: string, opts?: ToastOptions) => string`	—	Show an error toast; auto-dismisses after 8 s.
`toast.warning(msg, opts?)`	`(msg: string, opts?: ToastOptions) => string`	—	Show a warning toast; auto-dismisses after 8 s.
`toast.info(msg, opts?)`	`(msg: string, opts?: ToastOptions) => string`	—	Show an info toast; auto-dismisses after 5 s.
`toast.loading(msg, opts?)`	`(msg: string, opts?: ToastOptions) => string`	—	Show a sticky loading toast; stays visible until updated or dismissed.
`toast.dismiss(id?)`	`(id?: string \| null) => void`	—	Dismiss a toast by id, or all toasts if id is omitted.
`toast.update(id, patch?)`	`(id: string, patch?: Partial<ToastRecord>) => string`	—	Update a live toast in place; changing tone resets its auto-dismiss timer.
`toast.promise(promise, msgs?)`	`<T>(promise: Promise<T>, msgs?: { loading?: string; success?: string \| ((v: T) => string); error?: string \| ((e: unknown) => string) }) => Promise<T>`	—	Show a loading toast that transitions to success or error when the promise settles.
`toast.custom(node, opts?)`	`(node: unknown, opts?: { id?: string \| number; duration?: number; dismissible?: boolean }) => string`	—	Show a fully custom React node toast with no built-in chrome.
`opts.id`	`string \| number`	—	Stable key for deduplication and targeted updates via toast.update.
`opts.duration`	`number`	—	Auto-dismiss delay in ms; omit to use the tone preset.
`opts.description`	`string \| null`	—	Secondary line shown below the message.
`opts.action`	`{ label: string; onClick: () => void }`	—	Action button shown inside the toast; dismisses the toast after the click handler runs.

Toast playground

Install Toast

Usage

Toast props

Toast