Components
Toast
Short, non-blocking feedback for actions and background work.
Toast shows brief, non-blocking feedback such as a saved record, a failed request, or a finished
upload. Use it for results the user does not need to confirm. For decisions that require an answer,
use AlertDialog; for persistent warnings inside the page, use an inline alert.
The component is built on Base UI Toast. Base UI owns the queue, timers, swipe gestures, and live region announcements; Orkest UI owns the visual design and the imperative API.
Import the components from @orkest/ui/client.
Setup#
Render one ToastProvider and one ToastViewport at the application root. The provider connects
the imperative toast API to the viewport.
import { ToastProvider, ToastViewport } from '@orkest/ui/client';
export function App() {
return (
<ToastProvider>
{/* application */}
<ToastViewport position="bottom-right" />
</ToastProvider>
);
}Basic usage#
The imperative API works from event handlers, async functions, and modules outside React.
import { Button, Stack } from '@orkest/ui';
import { toast } from '@orkest/ui/client';
export function Example() {
return (
<Stack direction="row" gap={2} wrap>
<Button
variant="outline"
onClick={() => toast.success('Changes saved')}
>
Success
</Button>
<Button
variant="outline"
onClick={() => toast.error('Could not save')}
>
Error
</Button>
<Button
variant="outline"
onClick={() => toast.warning('Unsaved changes')}
>
Warning
</Button>
<Button
variant="outline"
onClick={() => toast.info('Copied to clipboard')}
>
Info
</Button>
</Stack>
);
}Types#
| Type | Default icon | Use |
|---|---|---|
success | CircleCheck | The operation succeeded. |
error | CircleX | The operation failed. |
warning | TriangleAlert | The user should pay attention. |
info | Info | Neutral confirmation or status. |
loading | LoaderCircle | Work is still running. Loading toasts never auto-dismiss. |
Only the icon carries the status color; the surface stays neutral in both themes.
Anatomy#
ToastProviderowns the queue, timeout, and limit.ToastViewportrenders the fixed stack and manages the live region.Toastis one notification root.ToastContentlays out the icon, text, action, and close button.ToastTitleandToastDescriptionrender the accessible title and description.ToastActionadds one optional action such as Undo.ToastClosedismisses the toast.ToastIconderives its icon from the toast type.
Descriptions and actions#
import { Button } from '@orkest/ui';
import { toast } from '@orkest/ui/client';
export function Example() {
function deleteTask() {
let toastId = '';
toastId = toast.show({
title: 'Task deleted',
description: 'The task moved to Trash.',
action: {
label: 'Undo',
onClick: () => toast.dismiss(toastId),
},
});
}
return (
<Button variant="outline" onClick={deleteTask}>
Delete task
</Button>
);
}Keep toasts short. Do not put forms or multi-step flows inside a toast.
Promise tracking#
toast.promise creates a loading toast and updates it in place when the promise settles.
import { Button } from '@orkest/ui';
import { toast } from '@orkest/ui/client';
function simulateUpload() {
return new Promise<void>((resolve) => {
window.setTimeout(resolve, 1600);
});
}
export function Example() {
return (
<Button
onClick={() =>
toast.promise(simulateUpload(), {
loading: 'Uploading file…',
success: 'Upload complete',
error: 'Upload failed',
})
}
>
Upload file
</Button>
);
}Managing toasts#
const id = toast.show({ title: 'Saving…', type: 'loading' });
toast.update(id, { title: 'Saved', type: 'success', duration: 4000 });
toast.dismiss(id); // close one toast
toast.dismissAll(); // close every toastAdding a toast with an existing id updates it instead of creating a duplicate. duration={0}
keeps a toast open until it is closed.
Positions#
import { useState } from 'react';
import { Button, Stack, Text } from '@orkest/ui';
import {
createToast,
ToastProvider,
ToastViewport,
type ToastPosition,
} from '@orkest/ui/client';
const positions: ToastPosition[] = [
'top-left',
'top-center',
'top-right',
'bottom-left',
'bottom-center',
'bottom-right',
];
export function Example() {
const [host] = useState(() => createToast());
const [position, setPosition] = useState<ToastPosition>('bottom-right');
return (
<ToastProvider toastManager={host.manager}>
<Stack gap={3}>
<Stack direction="row" gap={2} wrap>
{positions.map((item) => (
<Button
key={item}
size="sm"
variant={position === item ? 'primary' : 'outline'}
onClick={() => {
setPosition(item);
host.toast.info('Position: ' + item);
}}
>
{item}
</Button>
))}
</Stack>
<Text size="sm" tone="muted">
A local viewport opens in the selected corner.
</Text>
</Stack>
<ToastViewport position={position} />
</ToastProvider>
);
}Queue and limit#
ToastProvider shows at most limit toasts (default 3) and keeps older ones inert. timeout
sets the default auto-dismiss delay in milliseconds (default 5000).
import { useState } from 'react';
import { Button, Stack } from '@orkest/ui';
import {
createToast,
ToastProvider,
ToastViewport,
} from '@orkest/ui/client';
export function Example() {
const [host] = useState(() => createToast());
const [count, setCount] = useState(0);
return (
<ToastProvider toastManager={host.manager} limit={2}>
<Stack direction="row" gap={2} wrap>
<Button
variant="outline"
onClick={() => {
const next = count + 1;
setCount(next);
host.toast.info('Notification ' + next);
}}
>
Add notification
</Button>
<Button variant="ghost" onClick={() => host.toast.dismissAll()}>
Dismiss all
</Button>
</Stack>
<ToastViewport position="bottom-left" />
</ToastProvider>
);
}Hovering the viewport or focusing it with the keyboard pauses the timers. Press F6 to move focus
into the toast region and F6 again to return to the previous element.
Custom rendering#
Pass a render function to ToastViewport to replace the default item. Keep Toast as the root so
swipe behavior and timers stay intact.
<ToastViewport position="bottom-right">
{(toastObject) => (
<Toast toast={toastObject}>
<ToastContent>
<ToastIcon />
<div>
<ToastTitle />
<ToastDescription />
</div>
<ToastAction />
<ToastClose />
</ToastContent>
</Toast>
)}
</ToastViewport>Accessibility#
- The viewport is a labelled
regionwitharia-live="polite". - Toasts use
role="dialog"by default;priority: 'high'uses an alert announcement. - Toasts never steal focus.
F6moves focus into the region on demand. - The close button has the accessible name
Close notificationby default. Override it withlabelonToastClose. - Actions are real buttons and are reachable with the keyboard.
- Status is conveyed by an icon shape and text, not by color alone.
- Motion respects
prefers-reduced-motion; swipe-to-dismiss remains available.
Props#
ToastProvider#
| Prop | Type | Default |
|---|---|---|
timeout | number | 5000 |
| Default auto-dismiss delay in milliseconds. `0` keeps toasts open. | ||
limit | number | 3 |
| Maximum number of visible toasts. | ||
toastManager | ToastManager | — |
| Connects the imperative API to this provider. Defaults to the shared `toast` manager. | ||
children | ReactNode | — |
| Application content. The viewport is usually rendered as a sibling. | ||
ToastViewport#
| Prop | Type | Default |
|---|---|---|
position | 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'bottom-right' |
| Corner or edge where the toast stack is anchored. | ||
children | (toast) => ReactNode | — |
| Optional custom renderer for every toast. | ||
container | HTMLElement | ShadowRoot | RefObject | null | — |
| Portal container. Defaults to the document body. | ||
className | string | — |
| Additional class for the viewport element. | ||
Toast and parts#
| Prop | Type | Default |
|---|---|---|
toast | ToastObject | — |
| Toast object from `ToastViewport` or `useToast`. Required on `Toast`. | ||
swipeDirection | 'up' | 'down' | 'left' | 'right' | Array | ['down', 'right'] |
| Directions in which the toast can be swiped to dismiss. | ||
ToastIcon.type | ToastType | — |
| Overrides the type inherited from the surrounding `Toast`. | ||
ToastIcon.icon | LucideIcon | — |
| Overrides the default icon for the type. | ||
ToastClose.label | string | 'Close notification' |
| Accessible name of the close button. | ||
Imperative API#
| Prop | Type | Default |
|---|---|---|
toast.show | (options) => string | — |
| Adds a toast and returns its ID. | ||
toast.success / error / warning / info / loading | (title, options?) => string | — |
| Adds a typed toast. Loading toasts stay open until updated or dismissed. | ||
toast.promise | (promise, messages, options?) => Promise | — |
| Shows loading, then updates the same toast to success or error. | ||
toast.update | (id, options) => void | — |
| Updates a toast in place. | ||
toast.dismiss | (id?) => void | — |
| Closes one toast, or every toast when the ID is omitted. | ||
toast.dismissAll | () => void | — |
| Closes every toast. | ||
createToast | () => { manager, toast } | — |
| Creates an isolated manager and API for a nested provider. | ||