Skip to content
Browse documentation
whisk/ui

Toast

Provide short-lived feedback after an action.

Overview

Toast gives brief, non-blocking feedback after an application action. Create one application-owned controller and render it through one Toaster; the Toast component only renders a single notification and does not own a queue or timeout.

Use when

An action needs brief, non-blocking feedback after it completes or fails.

Use instead

Use Alert when the message must remain available in the page context.

Usage

tsx
import { Button, Toaster, createToaster } from "@smoothie-framework/whisk-react";

// Create this for one browser application instance, not for a shared server request.
const toaster = createToaster();

export function WorkspaceActions() {
  return <>
    <Button onClick={() => toaster.success({ title: "Saved", description: "Workspace updated." })}>
      Save changes
    </Button>
    <Toaster controller={toaster} position="top-right" />
  </>;
}

Examples

Mount one notification host

Render one Toaster near the application root. The controller accepts one mounted Toaster, so do not mount the same controller in a page, dialog, or feature boundary as well.

tsx
import { Toaster, createToaster } from "@smoothie-framework/whisk-react";

// Keep this in the browser application entry, not in shared server state.
export const toaster = createToaster({ duration: 5000 });

export function Notifications() {
  return <Toaster
    controller={toaster}
    position="bottom-right"
    max={2}
    offset="1.5rem"
  />;
}

Report a completed action

Use the status helper for ordinary outcomes. A status changes the icon and appearance, not the live-region urgency.

tsx
import { Button } from "@smoothie-framework/whisk-react";
import { toaster } from "./toaster";

<Button
  onClick={() => toaster.success({
    title: "Workspace saved",
    description: "Changes are available to your team.",
  })}
>
  Save changes
</Button>

Keep async feedback in one record

promise first creates an infinite loading toast, then updates that same record. Its result is the original promise, so awaiting it still preserves application error handling.

tsx
import { toaster } from "./toaster";

async function saveWorkspace() {
  const response = await fetch("/api/workspace", { method: "PUT" });
  if (!response.ok) throw new Error("Workspace save failed");
}

const { result } = toaster.promise(saveWorkspace(), {
  loading: { title: "Saving workspace" },
  success: { title: "Workspace saved" },
  error: {
    title: "Could not save workspace",
    description: "Try again from the workspace settings.",
    role: "alert",
  },
});

await result;

Offer one recoverable action

An action is optional and does not dismiss the toast for you. Dismiss it in the handler if that matches the completed recovery flow.

tsx
import { toaster } from "./toaster";

async function retryUpload() {
  const response = await fetch("/api/uploads/retry", { method: "POST" });
  if (!response.ok) throw new Error("Upload retry failed");
}

const id = toaster.error({
  title: "Upload failed",
  description: "Your file was not uploaded.",
  actionLabel: "Retry upload",
  onAction: () => {
    void retryUpload().finally(() => toaster.dismiss(id));
  },
  duration: "infinite",
});

Render a local notification deliberately

Toast alone is presentation only. Use it when the application already owns a local lifecycle; it will not create a queue, start a timeout, or move focus.

tsx
import { Toast } from "@smoothie-framework/whisk-react";

function dismissPreview() {
  // Update the application-owned local state that renders this Toast.
}

<Toast
  title="Preview refreshed"
  description="Your local preview now includes the latest changes."
  status="info"
  closable
  onClose={dismissPreview}
/>

Props

Component props

PropTypeDefaultDescription
createToasterCreateToasterOptionsduration: 5000 | pauseOnPageIdle: trueCreate an application-owned controller. It owns records and timers but is not shared between controllers or server requests.
controllerToastControllerrequired on ToasterPass the application-owned controller to exactly one mounted Toaster.
position | max | offsetToastPosition | number | number | stringtop-center | 3 | 16Place the Toaster, cap visible FIFO entries, and set its viewport offset. Queued entries are not rendered or timed.
title | descriptionstring | stringrequired | noneState the result in a short title and add only the context or recovery detail a person needs.
status | iconStyleToastStatus | ToastIconStyledefault | outlineChoose the visual feedback state and icon treatment. Status never changes announcement urgency by itself.
role | duration"status" | "alert" | number | "infinite"status | controller defaultChoose polite or urgent announcement behavior and the visible, unpaused duration. Loading defaults to infinite.
actionLabel | onActionstring | () => voidnone | noneAdd one optional recovery action. Supply both values together; calling the action does not dismiss the toast automatically.
closable | closeLabelboolean | stringcontroller: true | Toast: falseShow a dismissal button and name it for assistive technology. Controller-created toasts use Close notification unless you set closeLabel.
aria-labelstringToaster: NotificationsName the notification region or an individual Toast when its visible text does not provide an adequate name.
onDismiss | onStatusChange(reason: "dismiss" | "timeout") => void | (status: ToastStatusChange) => voidnone | noneObserve removal or queue lifecycle. The controller also exposes create, update, dismiss, pause, resume, promise, and dispose methods.

Accessibility

Toaster names its notification region as Notifications by default. Each Toast is atomic and announces politely with role=status unless you explicitly set role=alert, which announces assertively. Do not infer alert urgency from a warning or error status. Keep validation errors, consequential recovery actions, and information people may need later in persistent page content because a toast can expire. Provide a clear closeLabel when you change the default, and use an action label that explains the result of activation.

Content guidance

Use a short past-tense result for success, such as Project saved. For errors, name the problem and the available recovery action in one sentence.