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
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.
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.
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.
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.
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.
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
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.