--- title: Toast description: Brief notifications with actions, automatic dismissal, and loading states for async work. --- **bun** ```bash bun add @data-slot/toast ``` **npm** ```bash npm install @data-slot/toast ``` **pnpm** ```bash pnpm add @data-slot/toast ``` ## Anatomy Only `toast-viewport` is required inside the root. Each call to `show()` clones `toast-template` and fills its title, description, and action slots. Without a template, the component creates default markup that you can style with the same slots. Include `toast-close` to let people dismiss a notification themselves. ```html
    ``` Set the viewport’s position and the items’ appearance in CSS. `data-position` supplies a placement token; it does not position the viewport by itself. Add `data-portal` to move the viewport to `document.body` when it needs to escape a clipping container. ## Examples ### Show a notification Call `show()` with a title, an optional description, and a type. Add an action such as Undo with its own callback. Notifications dismiss after five seconds by default; hover or focus the stack to pause the timer and expand older items. Use `duration: 0` for a notification that stays until dismissed. The summary notification has a longer description, so the stack measures each item and keeps its offsets correct when heights differ. The viewport shows up to three notifications by default. Older items stay mounted but become hidden and non-interactive until space opens. Error and warning messages use `role="alert"`; other types use `role="status"` so they can be announced without moving focus. ### Follow an async operation Pass a promise to `promise()` to show a persistent loading message, then update that same notification when the operation resolves or rejects. The buttons below simulate both outcomes. Success and error notifications use the normal dismissal timer. `promise()` returns an object with `id` and `unwrap()`. Await `unwrap()` when you also need the result in your application, and handle a rejected promise with `try` / `catch`. For other updates, keep the id returned by `show()` and pass it to `update()` or `dismiss()`. ## API reference ### `create(scope?)` Auto-discover and bind uninitialized toast roots in a scope (`document` by default). Roots already initialized with either `create()` or `createToast()` are skipped. ```ts import { create } from "@data-slot/toast"; const controllers = create(); // ToastController[] ``` ### `createToast(root, options?)` Create a controller for one toast root. Repeated calls for the same root return the existing controller and keep its original options. Destroy that controller before rebinding with different options. ```ts import { createToast } from "@data-slot/toast"; const toaster = createToast(element, { limit: 3, duration: 5000, position: "bottom-right", pauseOnHover: true, pauseOnFocus: true, portal: false, onShow: (id) => console.log("shown", id), onDismiss: (id) => console.log("dismissed", id), onAction: (id, value) => console.log("action", id, value), }); ``` ### Options | Option | Type | Default | Description | |--------|------|---------|-------------| | `limit` | `number` | `3` | Maximum visible toasts at once; older toasts stay mounted with `data-visible="false"` | | `duration` | `number` | `5000` | Default auto-dismiss duration in ms (`0` = persistent) | | `position` | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"bottom-right"` | Position token exposed as `data-position` on root and viewport | | `pauseOnHover` | `boolean` | `true` | Pause all active timers while viewport is hovered | | `pauseOnFocus` | `boolean` | `true` | Pause all active timers while viewport has focus within | | `portal` | `boolean` | `false` | Portal viewport to `document.body` | | `onShow` | `(id: string) => void` | `undefined` | Callback when a toast is shown | | `onDismiss` | `(id: string) => void` | `undefined` | Callback when a toast starts dismissing | | `onAction` | `(id: string, value: string \| undefined) => void` | `undefined` | Callback when action button is clicked | Timers also pause automatically while the document is hidden or the window loses focus. ### `show(options)` ```ts const id = toaster.show({ id: "save-1", title: "Saved", description: "Your profile was updated", type: "success", duration: 4000, dismissible: true, closeButtonAriaLabel: "Close notification", testId: "save-toast", action: { label: "Undo", value: "undo-save", onClick: () => console.log("undo"), }, }); ``` `title` is required. If `id` is reused, the previous toast is force-replaced. `action.onClick` may call `event.preventDefault()` to keep the toast open. ### `promise(input, options)` ```ts const handled = toaster.promise(fetch("/api/save"), { loading: "Saving...", success: "Saved", error: (error) => ({ title: error instanceof Error ? error.message : "Save failed", }), }); await handled.unwrap(); ``` `promise()` keeps a stable toast id across loading/success/error states and returns `{ id, unwrap() }`. Each state is applied as a patch: `title`, `type`, and `duration` fall back to state defaults, and any other field a state omits stays as the loading state set it. ### Controller | Method / Property | Description | |-------------------|-------------| | `show(options)` | Create and show a toast, returns its id | | `update(id, patch)` | Patch an existing active toast in place (visible or overflow-hidden). Omitted or `undefined` fields are unchanged; `null` clears `description`, `action`, `closeButtonAriaLabel`, or `testId` | | `promise(input, options)` | Drive loading/success/error toast states from a promise, returns `{ id, unwrap() }` | | `dismiss(id)` | Dismiss one toast | | `dismissAll()` | Dismiss all active toasts | | `count` | Total active (non-exiting) toast count, including overflow-hidden items | | `destroy()` | Cleanup listeners, timers, observers and restore portaled viewport | ### Slots #### Required - `toast-viewport` #### Optional - `toast-template` (`