Toast
⋯
Toast uses Base UI’s notification behavior. Its success treatment adapts the Figma layer named “Alert Success”: a white surface, neutral 1px border, 12px radius, 20px badge-check icon, medium 14px title, and regular 14px description. The Figma layer is a 731px-wide alert inside a sheet; Toast uses the same anatomy in a narrower top-right notification viewport, so it is not an exact-width copy. Other status icons use existing semantic tokens without implying unprovided Figma variants.
Import Toast and useToastManager from @nesra/ui/toast or the package root. Mount one provider around the controls that create notifications, with one viewport and list inside it.
import { Toast, useToastManager } from "@nesra/ui/toast";
function SaveButton() { const manager = useToastManager(); return <button onClick={() => manager.add({ title: "Saved" })}>Save</button>;}
export function App() { return ( <Toast.Provider> <SaveButton /> <Toast.Viewport> <Toast.List /> </Toast.Viewport> </Toast.Provider> );}Composition
Section titled “Composition”Toast.Provider├── Application controls (useToastManager)└── Toast.Viewport (portal) └── Toast.List └── Toast.Root (one per managed toast) └── Toast.Content ├── Toast.Title ├── Toast.Description ├── Toast.Action (optional) └── Toast.CloseToast.List renders the standard composition. For custom content, pass a function as its child; the list still creates each Toast.Root and passes the managed ToastItem to the function. For example, <Toast.List>{(item) => <Toast.Content><Toast.Title>{item.title}</Toast.Title><Toast.Close /></Toast.Content>}</Toast.List>. Use Toast.Title and Toast.Description without children to read the manager’s values automatically.
Examples
Section titled “Examples”Title and description
Section titled “Title and description”import { Button } from "@nesra/ui/button";import { Toast, useToastManager } from "@nesra/ui/toast";
function NotifyButton() { const manager = useToastManager(); return ( <Button onClick={() => manager.add({ title: "Success! The TikTok ads account has been connected.", description: "Welcome back, your insights are ready!", type: "success", }) } > Show success toast </Button> );}
export function ToastBasicExample() { return ( <Toast.Provider> <NotifyButton /> <Toast.Viewport> <Toast.List /> </Toast.Viewport> </Toast.Provider> );}Title only
Section titled “Title only”For a brief confirmation, omit description.
import { Button } from "@nesra/ui/button";import { Toast, useToastManager } from "@nesra/ui/toast";
function TitleOnlyButton() { const manager = useToastManager(); return <Button onClick={() => manager.add({ title: "Settings saved" })}>Title only</Button>;}
export function ToastTitleOnlyExample() { return ( <Toast.Provider> <TitleOnlyButton /> <Toast.Viewport> <Toast.List /> </Toast.Viewport> </Toast.Provider> );}Description only
Section titled “Description only”When title is omitted, Base UI uses the description as the toast’s accessible message.
import { Button } from "@nesra/ui/button";import { Toast, useToastManager } from "@nesra/ui/toast";
function DescriptionOnlyButton() { const manager = useToastManager(); return ( <Button onClick={() => manager.add({ description: "Your changes have been saved and are available to the team." }) } > Description only </Button> );}
export function ToastDescriptionOnlyExample() { return ( <Toast.Provider> <DescriptionOnlyButton /> <Toast.Viewport> <Toast.List /> </Toast.Viewport> </Toast.Provider> );}Status treatments
Section titled “Status treatments”type selects a status icon. These four values use existing semantic tokens on the same neutral card surface. It does not change the announcement priority; include the outcome in the notification text.
import { Button } from "@nesra/ui/button";import { Toast, useToastManager } from "@nesra/ui/toast";
const notifications = [ { type: "success", title: "Upload complete", description: "Your file is ready." }, { type: "info", title: "New version available", description: "Review the latest changes." }, { type: "warning", title: "Storage almost full", description: "Only 10% remains." }, { type: "error", title: "Upload failed", description: "Check your connection and retry." },] as const;
function StatusButtons() { const manager = useToastManager(); return ( <div className="flex flex-wrap gap-3"> {notifications.map((notification) => ( <Button key={notification.type} onClick={() => manager.add(notification)} variant="outline"> {notification.type} </Button> ))} </div> );}
export function ToastStatusesExample() { return ( <Toast.Provider> <StatusButtons /> <Toast.Viewport> <Toast.List /> </Toast.Viewport> </Toast.Provider> );}Multiple toasts
Section titled “Multiple toasts”The viewport shows up to limit toasts. This example keeps three open. Hover over or focus the stack to expand it, then dismiss each notification or swipe it away on touch.
import { Button } from "@nesra/ui/button";import { Toast, useToastManager } from "@nesra/ui/toast";
function MultipleButton() { const manager = useToastManager(); return ( <Button onClick={() => { manager.add({ title: "Report created", description: "The report is ready to review." }); manager.add({ title: "Team notified", description: "Everyone can now access it." }); manager.add({ title: "Link copied", description: "Share it wherever you need." }); }} > Show three toasts </Button> );}
export function ToastMultipleExample() { return ( <Toast.Provider timeout={0} limit={3}> <MultipleButton /> <Toast.Viewport> <Toast.List /> </Toast.Viewport> </Toast.Provider> );}Update an existing toast
Section titled “Update an existing toast”add returns an ID. Pass it to update to change that same notification. The functional form receives its current state; a repeated click uses the same ID rather than creating another toast.
import { Button } from "@nesra/ui/button";import { Toast, useToastManager } from "@nesra/ui/toast";
function UpdateButton() { const manager = useToastManager(); return ( <Button onClick={() => { const id = manager.add({ id: "report-export", title: "Preparing report", description: "Collecting the latest data.", type: "info", timeout: 0, }); window.setTimeout(() => { manager.update(id, (current) => ({ title: current.title === "Preparing report" ? "Report ready" : "Export complete", description: "The report is ready to download.", type: "success", timeout: 5000, })); }, 1200); }} > Export report </Button> );}
export function ToastUpdateExample() { return ( <Toast.Provider> <UpdateButton /> <Toast.Viewport> <Toast.List /> </Toast.Viewport> </Toast.Provider> );}Custom composition
Section titled “Custom composition”The Toast.List child function replaces the standard content while preserving the managed root. Keep a title or description and a close control in a custom notification.
import { Button } from "@nesra/ui/button";import { Toast, useToastManager } from "@nesra/ui/toast";
function CustomButton() { const manager = useToastManager(); return ( <Button onClick={() => manager.add({ title: "Invoice exported", description: "invoice-2026-09.pdf", type: "success", }) } > Show custom toast </Button> );}
export function ToastCustomExample() { return ( <Toast.Provider> <CustomButton /> <Toast.Viewport> <Toast.List> {() => ( <Toast.Content> <div className="min-w-0 flex-1 space-y-1"> <Toast.Title /> <Toast.Description /> <p className="type-nesra-body-xsmall-regular text-nesra-text-support"> Available in your downloads. </p> </div> <Toast.Close /> </Toast.Content> )} </Toast.List> </Toast.Viewport> </Toast.Provider> );}Action and persistent notification
Section titled “Action and persistent notification”timeout={0} keeps notifications open until dismissed. An action is an application callback; the application must implement undo or another effect. Calling manager.close() dismisses the latest toast.
import { Button } from "@nesra/ui/button";import { Toast, useToastManager } from "@nesra/ui/toast";
function DeleteButton() { const manager = useToastManager(); return ( <Button onClick={() => manager.add({ title: "Item removed", description: "You can undo this change.", type: "warning", actionProps: { children: "Undo", onClick: () => { // Restore the item in your application's state here. manager.close(); }, }, }) } variant="outline" > Remove item </Button> );}
export function ToastActionsExample() { return ( <Toast.Provider timeout={0}> <DeleteButton /> <Toast.Viewport> <Toast.List /> </Toast.Viewport> </Toast.Provider> );}Promise lifecycle
Section titled “Promise lifecycle”promise shows loading feedback and then updates that toast with the result. This example uses a simulated export; replace the promise with an application operation. Provide a failure state for operations that can reject.
import { Button } from "@nesra/ui/button";import { Toast, useToastManager } from "@nesra/ui/toast";
function PromiseButton() { const manager = useToastManager(); return ( <Button onClick={() => { const exportFile = new Promise<string>((resolve) => { window.setTimeout(() => resolve("team-report.csv"), 1500); }); void manager.promise(exportFile, { loading: { title: "Exporting report", description: "Please wait.", timeout: 0 }, success: (filename) => ({ title: "Export ready", description: filename, type: "success", timeout: 5000, }), error: { title: "Export failed", type: "error", priority: "high" }, }); }} > Export with promise </Button> );}
export function ToastPromiseExample() { return ( <Toast.Provider> <PromiseButton /> <Toast.Viewport> <Toast.List /> </Toast.Viewport> </Toast.Provider> );}Urgent notification
Section titled “Urgent notification”priority: "high" requests an assertive announcement. Use it only when the message requires prompt attention. This example also persists until dismissal; status styling alone never sets priority.
import { Button } from "@nesra/ui/button";import { Toast, useToastManager } from "@nesra/ui/toast";
function PriorityButton() { const manager = useToastManager(); return ( <Button onClick={() => manager.add({ title: "Connection lost", description: "Your changes may not be saved. Reconnect to continue.", type: "error", priority: "high", timeout: 0, }) } variant="destructive" > Show urgent message </Button> );}
export function ToastPriorityExample() { return ( <Toast.Provider> <PriorityButton /> <Toast.Viewport> <Toast.List /> </Toast.Viewport> </Toast.Provider> );}Light and Dark
Section titled “Light and Dark”Toasts use --nesra-surface-card-bg-neutral, --nesra-stroke-border, and shadow-nesra-lg, with
--nesra-text-headline titles and --nesra-text-support descriptions, so they follow the active
theme. Keyboard focus on a toast or the viewport shows shadow-nesra-focus-ring, the Figma
3px focus ring.
Accessibility
Section titled “Accessibility”Base UI announces notifications in a polite live region by default. Set priority: "high" on an urgent notification to use its assertive announcement. The viewport is a named “Notifications” region. Press F6 to move focus into it; keyboard focus and pointer hover pause auto-dismiss, and focus can return to its previous location. Each default toast provides a labeled dismiss button. The application must supply meaningful text, an action label and handler when needed, and enough time to read or a persistent timeout for consequential messages. Do not rely on color or an auto-dismissed toast as the only record of an important outcome.
API reference
Section titled “API reference”Toast.Provider
Section titled “Toast.Provider”Forwards Base UI Provider props. The provider owns the manager and timeout behavior.
| Prop | Type | Default | Effect |
|---|---|---|---|
timeout |
number (ms) |
5000 |
Auto-dismiss delay; 0 persists. |
limit |
number |
3 |
Maximum visible toasts; older items become inert. |
children |
ReactNode |
— | Controls and viewport within the scope. |
Toast.Viewport
Section titled “Toast.Viewport”Forwards Base UI Viewport props, including className and a ref to the region. container accepts the Base UI Portal target; by default the viewport portals to document.body. The viewport is fixed at the upper right with a 12px small-screen inset and a maximum width of 380px. It stacks one layer above Sheet, Dialog, and popups, so a toast raised while one of them is open stays visible.
Toast.List
Section titled “Toast.List”| Prop | Type | Default | Effect |
|---|---|---|---|
children |
(toast: ToastItem) => ReactNode |
Standard toast composition | Custom content for each managed toast. |
Toast.Root, Toast.Content, Toast.Title, Toast.Description, Toast.Action, Toast.Close
Section titled “Toast.Root, Toast.Content, Toast.Title, Toast.Description, Toast.Action, Toast.Close”Toast.Root requires a toast: ToastItem; Toast.List supplies it automatically. It forwards Base UI Root props, including swipe direction and className. The other parts forward their respective Base UI props and refs. Title and description read managed values when children are omitted. Action reads actionProps and renders only when it has content. Close dismisses its own toast and defaults to an icon button labeled “Dismiss notification”; override its children and label for a custom control.
useToastManager
Section titled “useToastManager”Use inside Toast.Provider. add(options) returns an ID and accepts title, description, type, priority, timeout, actionProps, and callbacks from Base UI. close(id?) closes a specific toast or the latest. update(id, options) updates a toast. promise(promise, options) manages loading and result notifications. toasts contains the live ToastItem[]. type is an arbitrary string; info, success, warning, and error receive colored icons from semantic tokens. Other values retain the neutral treatment. priority defaults to "low" regardless of type. An action’s effect remains the application’s responsibility.
See colors, typography, and shape and elevation for the tokens used here.