Skip to content

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>
);
}
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.Close

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

For a brief confirmation, omit description.

When title is omitted, Base UI uses the description as the toast’s accessible message.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.