ArcaneToast#

A toast notification system with a simple global API. Supports all variants (info, success, warning, error, loading) with configurable positioning and action buttons.

Aliases: ArcaneToast, AToast

Setup#

Add the toast container once at the root of your app:

ArcaneToast.container(
  position: ToastPosition.bottomRight,
)

Basic Usage#

Use the global toast accessor anywhere in your app:

// Info toast
toast.info('This is an info message');

// Success toast
toast.success('Item saved successfully');

// Warning toast
toast.warning('Please review your input');

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

// Loading toast (no auto-dismiss)
toast.loading('Processing...');

Container Properties#

Toast Positions#

ArcaneToast.container(position: ToastPosition.topLeft)
ArcaneToast.container(position: ToastPosition.topCenter)
ArcaneToast.container(position: ToastPosition.topRight)
ArcaneToast.container(position: ToastPosition.bottomLeft)
ArcaneToast.container(position: ToastPosition.bottomCenter)
ArcaneToast.container(position: ToastPosition.bottomRight) // default

With Title and Description#

toast.success(
  'Changes saved',
  title: 'Success',
  description: 'Your profile has been updated.',
);

With Action Button#

toast.info(
  'Item deleted',
  action: ToastAction(
    label: 'Undo',
    onPressed: () => undoDelete(),
  ),
);

// Destructive action
toast.error(
  'Failed to save',
  action: ToastAction(
    label: 'Delete Draft',
    onPressed: () => deleteDraft(),
    destructive: true,
  ),
);

Loading Toast#

// Show loading toast
final id = toast.loading('Uploading file...');

// Later, update it to success
ToastManager.instance.update(id, (t) => t.copyWith(
  message: 'Upload complete!',
  variant: ToastVariant.success,
  duration: 4000,
  dismissible: true,
));

// Or dismiss it
toast.dismiss(id);

Promise Toast#

Automatically updates based on async result:

toast.promise(
  saveData(),
  loading: 'Saving...',
  success: (result) => 'Saved ${result.name}!',
  error: (e) => 'Failed: ${e.message}',
);

Custom Duration#

Duration is in milliseconds:

// Quick toast (2 seconds)
toast.info('Quick message', duration: 2000);

// Default durations:
// - info/success: 4000ms
// - warning: 5000ms
// - error: 6000ms
// - loading: 0 (no auto-dismiss)

Per-Toast Positioning#

Override the default position for individual toasts:

toast.error(
  'Critical error!',
  position: ToastPosition.topCenter,
);

Dismissing Toasts#

// Get toast ID from any toast method
final id = toast.success('Saved!');

// Dismiss specific toast
toast.dismiss(id);

// Dismiss all toasts
toast.dismissAll();

Custom Icon#

toast.success(
  'Copied to clipboard',
  icon: ArcaneIcon.copy(size: IconSize.md),
);

Standalone Toast Component#

For controlled usage without the global API:

ArcaneToast(
  message: 'Operation completed successfully',
  variant: ToastVariant.success,
  onClose: () => print('Toast closed'),
)

Component Properties#

All Variants#

• info - Blue accent, info circle icon
• success - Green accent, checkmark icon
• warning - Yellow/orange accent, warning triangle icon
• error - Red accent, X icon
• loading - Accent color, animated spinner icon

Static Site Support#

The JavaScript fallback system fully supports all features:

• Creates toaster container dynamically
• Proper variant-specific colors and SVG icons
• Progress bar with hover pause
• Auto-dismiss with configurable duration
• Action buttons with callbacks
• Respects positioning settings

Demo buttons containing "Success", "Error", "Warning", "Info", or "Loading" text automatically trigger toasts.

Example: Form Submission#

void submitForm() {
  toast.promise(
    saveFormData(),
    loading: 'Submitting form...',
    success: (_) => 'Form submitted successfully!',
    error: (e) => 'Failed to submit: ${e.message}',
  );
}

Example: Undo Action#

void deleteItem(Item item) {
  removeItem(item);
  toast.info(
    '${item.name} deleted',
    action: ToastAction(
      label: 'Undo',
      onPressed: () => restoreItem(item),
    ),
  );
}

Example: Manual Dismiss Required#

For critical notifications that require user acknowledgment:

// Acknowledgment required - no auto-dismiss, no close button
ArcaneToast(
  title: 'Session Warning',
  message: 'Your session will expire in 5 minutes.',
  variant: ToastVariant.warning,
  duration: 0,           // No auto-dismiss
  dismissible: false,    // No close button
  action: ToastAction(
    label: 'OK',
    onPressed: () => dismissToast(),
  ),
)

// Destructive confirmation
ArcaneToast(
  title: 'Are you sure?',
  message: 'This action cannot be undone.',
  variant: ToastVariant.error,
  duration: 0,
  dismissible: false,
  action: ToastAction(
    label: 'I Understand',
    onPressed: () => proceedWithAction(),
    destructive: true,
  ),
)

Related Components#

• ArcaneAlertBanner - Inline alerts