Toast

A stacked, auto-dismissing message anchored to the top or bottom of the screen. Wrap your app in ToastProvider, then call useToast().show(...) from anywhere inside it. Each variant (success/error/warning/info) shows a default icon from @devraj-labs/vajra-ui-icons automatically — pass icon to override it, or null to hide it. Pass dismissible: true to show a close button.

Up to maxVisible toasts (default 3, set via the theme's toast.maxVisible or the maxVisible prop) stack on screen at once, newest closest to the anchored edge. Extra show() calls stay queued and appear automatically as visible toasts are dismissed.

function ToastDemo() {
  const { show } = useToast();

  useEffect(() => {
    show({ message: 'Saved successfully.', duration: 0, dismissible: true });
    show({ message: 'Profile updated.', variant: 'success', duration: 0, dismissible: true });
    show({ message: 'Something went wrong.', variant: 'error', duration: 0, dismissible: true });
  }, []);

  return null;
}

function App() {
  return (
    <ToastProvider>
      <ToastDemo />
    </ToastProvider>
  );
}

Stacking

Calling show() multiple times stacks the toasts instead of queuing them behind a single visible one. By default up to 3 stack at once; a 4th show() call stays queued until one of the visible toasts is dismissed — the fourth here never appears until you dismiss one of the first three.

<ToastProvider maxVisible={3}>
  <StackDemo />
</ToastProvider>

Top-anchored

<ToastProvider position="top">
  <TopToastDemo />
</ToastProvider>

Props

ToastProvider

Prop	Type	Default	Description
children	ReactNode		Required. Subtree that gets access to useToast().
position	'top' | 'bottom'	'bottom'	Where the toast stack is anchored on screen.
maxVisible	number	theme's toast.maxVisible (3)	Maximum number of toasts stacked on screen at once. Extra show() calls stay queued.

useToast()

Return	Type	Description
show	(options: TToastOptions | string) => string	Enqueues a toast. Accepts a plain message string or a TToastOptions object. Returns the generated toast id.
hide	(id: string) => void	Removes a queued/visible toast by id.

TToastOptions

Prop	Type	Default	Description
message	string		Required. Toast text.
variant	'default' | 'success' | 'error' | 'warning' | 'info'	'default'	Visual style. Also selects the default icon.
duration	number	3000	Milliseconds before auto-dismiss. Pass 0 to disable auto-dismiss.
icon	ReactNode	variant default	Overrides the variant's default icon. Pass null to render no icon.
dismissible	boolean	false	Shows a dismiss (✕) button that closes the toast on press.

Up to maxVisible toasts stack at once; additional calls to show are queued and displayed in order as visible toasts are dismissed. useToast throws if called outside a ToastProvider.

Set the default globally via createVajraTheme({ toast: { maxVisible: 5 }, ... }), or override it per-provider with the maxVisible prop.