Toast

Toast notification system for editor feedback. Provides severity-based notifications (info, success, warning, error) with auto-dismiss timers, pause-on-hover, progress bars, action buttons, and configurable screen positioning. Uses a provider/hook pattern for triggering toasts from anywhere in the component tree.

Live Preview

Import

import { ToastProvider, useToast } from 'entangle-ui';

Setup

Wrap your application (or a section of it) with ToastProvider. Then use the useToast() hook in any child component.

function App() {
  return (
    <ToastProvider position="bottom-right">
      <Editor />
    </ToastProvider>
  );
}

Usage

function SaveButton() {
  const { success, error } = useToast();

  const handleSave = async () => {
    try {
      await saveProject();
      success('Project saved successfully');
    } catch (err) {
      error('Failed to save project', { title: 'Save Error' });
    }
  };

  return <Button onClick={handleSave}>Save</Button>;
}

Severity Levels

Each severity level has a distinct icon and color scheme.

const { info, success, warning, error } = useToast();

info('New update available');
success('File exported successfully');
warning('Running low on memory');
error('Failed to connect to server');

Severity	Use case	ARIA role
info	General information	status (polite)
success	Completed operations	status (polite)
warning	Important warnings	alert (assertive)
error	Errors and failures	alert (assertive)

Toast with Title

success('All changes have been saved to disk.', {
  title: 'Auto-Save Complete',
});

error('The file format is not supported. Try exporting as .glb instead.', {
  title: 'Export Failed',
});

Custom Duration

Override the default duration (in milliseconds) for individual toasts. Set to 0 for persistent toasts.

// Quick notification (2 seconds)
info('Copied to clipboard', { duration: 2000 });

// Persistent (no auto-dismiss)
warning('Unsaved changes detected', { duration: 0, closable: true });

Progress Bar

Show a visual progress indicator that tracks the remaining auto-dismiss time.

success('File uploaded', {
  showProgress: true,
  duration: 5000,
});

The progress bar pauses when the user hovers over the toast.

Action Button

Add an action button to the toast for quick responses.

const { toast } = useToast();

toast({
  message: 'Object deleted',
  severity: 'info',
  action: {
    label: 'Undo',
    onClick: () => undoDelete(),
  },
});

Custom Icon

Override the default severity icon with a custom React element.

toast({
  message: 'Render complete',
  severity: 'success',
  icon: <RenderIcon />,
});

Dismissing Toasts

Toasts with closable: true (the default) show a close button. You can also dismiss programmatically.

const { toast, dismiss, dismissAll } = useToast();

// Dismiss specific toast
const id = toast({ message: 'Processing...', severity: 'info', duration: 0 });
// Later...
dismiss(id);

// Dismiss all
dismissAll();

Full Toast API

The toast() function returns the toast ID and accepts the full ToastData object.

const { toast } = useToast();

const id = toast({
  title: 'Export Progress',
  message: 'Exporting 3D scene...',
  severity: 'info',
  duration: 0,
  closable: true,
  showProgress: false,
  icon: <SpinnerIcon />,
  action: {
    label: 'Cancel',
    onClick: () => cancelExport(),
  },
});

Positioning

The ToastProvider controls where toasts appear on screen.

<ToastProvider position="top-right">...</ToastProvider>
<ToastProvider position="top-center">...</ToastProvider>
<ToastProvider position="top-left">...</ToastProvider>
<ToastProvider position="bottom-right">...</ToastProvider>
<ToastProvider position="bottom-center">...</ToastProvider>
<ToastProvider position="bottom-left">...</ToastProvider>

Bottom positions stack toasts with the newest at the bottom (using column-reverse).

Provider Configuration

<ToastProvider
  position="bottom-right"
  maxVisible={5}
  defaultDuration={5000}
  gap={8}
  zIndex={1200}
>
  <App />
</ToastProvider>

Props

ToastProvider

Prop	Type	Default	Description
children	ReactNode	—	Application content.
position	'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center'	'bottom-right'	Screen position for the toast container.
maxVisible	number	5	Maximum number of visible toasts at once.
defaultDuration	number	5000	Default auto-dismiss duration in milliseconds.
gap	number	8	Gap between toasts in pixels.
zIndex	number	1200	Z-index of the toast container.

useToast() Return Value

Method	Type	Description
toast	(data: ToastData) => string	Create a toast with full configuration. Returns the toast ID.
info	(message: string, options?) => string	Shorthand for info severity.
success	(message: string, options?) => string	Shorthand for success severity.
warning	(message: string, options?) => string	Shorthand for warning severity.
error	(message: string, options?) => string	Shorthand for error severity.
dismiss	(id: string) => void	Dismiss a specific toast by ID.
dismissAll	() => void	Dismiss all visible toasts.

ToastData

Property	Type	Default	Description
message	string	required	Toast message text.
id	string	auto-generated	Custom toast ID.
title	string		Optional title displayed above the message.
severity	'info' | 'success' | 'warning' | 'error'	'info'	Severity level.
duration	number	5000	Auto-dismiss duration in ms. Set to 0 for persistent.
closable	boolean	true	Whether to show the close button.
showProgress	boolean	false	Whether to show the progress bar.
icon	ReactNode	severity icon	Custom icon element.
action	{ label: string; onClick: () => void }		Action button configuration.

Accessibility

• Info and success toasts use role="status" with aria-live="polite"
• Warning and error toasts use role="alert" with aria-live="assertive"
• The toast container is a role="region" with aria-label="Notifications"
• Close buttons have aria-label="Dismiss notification"
• Auto-dismiss timers pause on hover so users have time to read
• Toasts are rendered in a portal to avoid affecting the DOM structure