Toast

Displays temporary notification messages using Base UI Toast primitives.
1(function ToastPreview() {
2  return (
3    <Toast.Provider>
4      <Flex gap="medium" wrap="wrap">
5        <Button
6          onClick={() =>
7            toastManager.add({ title: "This is a toast", type: "success" })
8          }
9        >
10          Trigger toast
11        </Button>
12      </Flex>
13    </Toast.Provider>
14  );
15})

Anatomy

Import and set up the toast system:

1import { Toast, toastManager } from '@raystack/apsara'
2

3// Wrap your app with Toast.Provider (once, at root)
4<Toast.Provider position="bottom-right">
5  <App />
6</Toast.Provider>
7

8// Trigger toasts from anywhere
9toastManager.add({ title: 'Hello!', type: 'success' })

API Reference

Toast.Provider

Renders the toast viewport and manages the toast lifecycle. Place once at the root of your app.

Prop

Type

toastManager.add(options)

Creates a new toast and returns its unique ID. The toastManager can be imported and used anywhere — including outside React components (e.g., API interceptors, utility functions).

Prop

Type

toastManager methods

MethodSignatureDescription
add(options) => stringCreate a toast, returns its ID
close(id: string) => voidClose a specific toast by ID
update(id: string, options) => voidUpdate an existing toast's properties
promise(promise, { loading, success, error }) => PromiseCreate a toast that tracks a promise lifecycle

Examples

Basic Toast

1<Button onClick={() => toastManager.add({ title: "Hello from Apsara!" })}>
2  Show toast
3</Button>

Type Variants

Use the type prop to change the visual styling of the toast.

1<Button
2  onClick={() =>
3    toastManager.add({ title: "Saved successfully", type: "success" })
4  }
5>
6  Success
7</Button>

With Title and Description

1<Flex gap="medium" wrap="wrap">
2  <Button
3    onClick={() =>
4      toastManager.add({
5        title: "File uploaded",
6        description: "Your document has been uploaded successfully.",
7        type: "success",
8      })
9    }
10  >
11    With description
12  </Button>
13  <Button
14    onClick={() =>
15      toastManager.add({

With Action Button

Use actionProps to render an action button inside the toast.

1<Button
2  onClick={() =>
3    toastManager.add({
4      title: "Item deleted",
5      description: "1 item was moved to trash.",
6      actionProps: {
7        children: "Undo",
8        onClick: () =>
9          toastManager.add({ title: "Item restored", type: "success" }),
10      },
11    })
12  }
13>
14  Action toast
15</Button>

Promise Toast

Track an async operation with automatic loading, success, and error states.

1<Button
2  onClick={() => {
3    const promise = new Promise((resolve) => setTimeout(resolve, 2000));
4    toastManager.promise(promise, {
5      loading: "Loading data...",
6      success: "Data loaded successfully!",
7      error: "Failed to load data.",
8    });
9  }}
10>
11  Promise toast
12</Button>

Positioning

Control where toasts appear on screen with the position prop on Toast.Provider.

1<Button onClick={() => toastManager.add({ title: "Bottom right toast" })}>
2  Bottom Right
3</Button>

Close and Update

Create a toast, then update or close it programmatically using the returned ID.

1(function UpdateToast() {
2  const idRef = React.useRef(null);
3  return (
4    <Flex gap="medium" wrap="wrap">
5      <Button
6        onClick={() => {
7          idRef.current = toastManager.add({
8            title: "Processing...",
9            type: "loading",
10            timeout: 0,
11          });
12        }}
13      >
14        Start processing
15      </Button>

Accessibility

  • Uses aria-live regions for screen reader announcements
  • priority: 'high' uses role="alert" (assertive) for urgent notifications
  • priority: 'low' (default) uses role="status" (polite) for non-urgent notifications
  • Close button has aria-label="Close toast"
  • Supports keyboard navigation and Escape to dismiss
  • Swipe-to-dismiss gesture support