Skip to main content

​
Import

import { toast, ToastContainer } from '@raystack/apsara';

​
Setup

Add the ToastContainer component to your app root: 
function App() {
  return (
    <>
      <ToastContainer />
      {/* Your app content */}
    </>
  );
}

​
Usage

​
Basic toast

import { toast } from '@raystack/apsara';

function MyComponent() {
  return (
    <button onClick={() => toast('Hello World')}>
      Show Toast
    </button>
  );
}

​
Toast types

// Success toast
toast.success('Operation completed successfully!');

// Error toast
toast.error('Something went wrong!');

// Warning toast
toast.warning('Please be careful!');

// Info toast
toast.info('Here is some information.');

// Loading toast
toast.loading('Processing...');

​
Promise-based toast

const myPromise = fetch('/api/data');

toast.promise(myPromise, {
  loading: 'Loading data...',
  success: 'Data loaded successfully!',
  error: 'Failed to load data',
});

​
With custom duration

toast('This will disappear in 5 seconds', {
  duration: 5000,
});

​
With description

toast('Upload Complete', {
  description: 'Your file has been uploaded successfully.',
});

​
With action button

toast('File deleted', {
  action: {
    label: 'Undo',
    onClick: () => console.log('Undo clicked'),
  },
});

​
Dismissing toasts

// Dismiss a specific toast
const toastId = toast('This is a toast');
toast.dismiss(toastId);

// Dismiss all toasts
toast.dismiss();

​
With custom styling

toast('Custom styled toast', {
  style: {
    background: 'red',
    color: 'white',
  },
  className: 'my-custom-toast',
});

​
With callbacks

toast('Toast with callbacks', {
  onDismiss: () => console.log('Toast dismissed'),
  onAutoClose: () => console.log('Toast auto-closed'),
});

​
JSX content

toast(
  <div>
    <strong>Custom Content</strong>
    <p>You can use JSX in toasts</p>
  </div>
);

​
Loading states

​
Simple loading

const loadingToast = toast.loading('Processing...');

// Later, update to success
toast.success('Done!', { id: loadingToast });

​
Loading with promise

const promise = new Promise((resolve) => {
  setTimeout(() => resolve('Success!'), 2000);
});

toast.promise(promise, {
  loading: 'Loading...',
  success: (data) => `${data}`,
  error: 'Error',
});

​
API reference

​
toast()

The main function to display toast notifications. 
toast(message: string | ReactNode, options?: ToastOptions)
​
message
string | React.ReactNode
required
The content to display in the toast. Can be a string or JSX element.
​
options
ToastOptions
Configuration options for the toast.

​
Toast options

​
duration
number
default:"4000"
Time in milliseconds before the toast auto-dismisses. Set to Infinity to prevent auto-dismiss.
​
description
string
Additional description text displayed below the main message.
​
action
{ label: string; onClick: () => void }
Action button configuration with label and click handler.
​
id
string | number
Custom identifier for the toast. Useful for updating or dismissing specific toasts.
​
className
string
Additional CSS class names to apply to the toast.
​
style
CSSProperties
Inline styles to apply to the toast.
​
onDismiss
() => void
Callback function called when the toast is dismissed manually.
​
onAutoClose
() => void
Callback function called when the toast auto-closes after the duration.

​
toast.success()

Displays a success toast. 
toast.success(message: string | ReactNode, options?: ToastOptions)

​
toast.error()

Displays an error toast. 
toast.error(message: string | ReactNode, options?: ToastOptions)

​
toast.warning()

Displays a warning toast. 
toast.warning(message: string | ReactNode, options?: ToastOptions)

​
toast.info()

Displays an info toast. 
toast.info(message: string | ReactNode, options?: ToastOptions)

​
toast.loading()

Displays a loading toast. 
toast.loading(message: string | ReactNode, options?: ToastOptions)

​
toast.promise()

Displays a toast that updates based on promise state. 
toast.promise(
  promise: Promise<T>,
  options: {
    loading: string | ReactNode;
    success: string | ReactNode | ((data: T) => string | ReactNode);
    error: string | ReactNode | ((error: Error) => string | ReactNode);
  }
)

​
toast.dismiss()

Dismisses one or all toasts. 
toast.dismiss(id?: string | number)
​
id
string | number
The ID of the toast to dismiss. If omitted, all toasts will be dismissed.

​
ToastContainer

Container component that renders the toast notifications.
​
position
'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
Position where toasts appear on the screen.
​
theme
'light' | 'dark' | 'system'
Color theme for toasts. Defaults to system preference.
​
richColors
boolean
Whether to use rich colors for different toast types.
​
expand
boolean
Whether toasts expand to show full content on hover.
​
visibleToasts
number
default:"3"
Maximum number of toasts visible at once.