Toast Notifications

Toast notifications provide temporary feedback about actions or events. They appear briefly, don’t interrupt the user’s workflow, and disappear automatically or can be manually dismissed.

Overview

The Toast component delivers lightweight, contextual feedback that appears at the edge of the screen. Unlike alerts or modals, toasts are non-blocking and designed to communicate status updates, confirmations, or brief messages without requiring user interaction.

Interactive Demo

Basic Toast

Simple notification with title and message

Success Toast

Click to trigger a real toast notification

toast.success("Changes saved!", { title: "Success" })

Usage

Basic Implementation

<script>
import Toast from '$lib/notification/components/Toast.svelte';

const notification = {
  id: 'unique-id',
  type: 'success',
  title: 'Success',
  message: 'Changes saved successfully',
  duration: 5000,
  position: 'top-right',
  dismissible: true,
  createdAt: new Date(),
  priority: 1
};
</script>

<Toast
  {notification}
  onDismiss={(id) => handleDismiss(id)}
/>

Using the Toast Hook

The recommended way to show toasts is through the useToast() hook:

<script>
import { useToast } from '$lib/notification/components/use-toast';

const toast = useToast();

async function saveData() {
  try {
    await api.saveData();
    toast.success('Data saved successfully');
  } catch (error) {
    toast.error('Failed to save data');
  }
}
</script>

<button onclick={saveData}>Save</button>

With ToastProvider

Wrap your app with ToastProvider to enable the toast system:

<!-- app.html or +layout.svelte -->
<script>
import { ToastProvider } from '$lib/notification/components';
</script>

<ToastProvider>
  <!-- Your app content -->
  <main>
    <!-- Components can now use useToast() -->
  </main>
</ToastProvider>

Toast Types

Success

Confirm successful operations and completed actions.

When to use:

Form submissions completed
Files uploaded successfully
Settings saved
Actions completed

Error

Indicate failures or problems that need attention.

When to use:

API request failures
Validation errors
Network issues
Permission errors

Warning

Alert users to potential issues or important considerations.

When to use:

Quota limits approaching
Temporary system issues
Deprecation notices
Action confirmations needed

Info

Provide helpful information or neutral status updates.

When to use:

Feature announcements
System status updates
General notifications
Process started messages

Features

Auto-dismiss with Progress

Toasts automatically disappear after their duration expires. A progress bar shows remaining time:

<Toast
  notification={{
    ...baseNotification,
    duration: 5000 // 5 seconds
  }}
  showProgress={true}
/>

Pause on Hover

Progress pauses when users hover over the toast, resuming when they move away:

// Built-in behavior - no configuration needed
// Progress automatically pauses on hover
// Resumes on mouse leave with remaining time

Action Buttons

Include action buttons for user interaction:

<script>
const notificationWithActions = {
  ...baseNotification,
  type: 'info',
  title: 'Update Available',
  message: 'A new version is ready to install',
  actions: [
    { id: 'install', label: 'Install' },
    { id: 'later', label: 'Later' }
  ]
};

function handleAction(notificationId, actionId) {
  if (actionId === 'install') {
    startInstall();
  }
  toast.dismiss(notificationId);
}
</script>

<Toast
  notification={notificationWithActions}
  onAction={handleAction}
/>

Swipe to Dismiss

Touch-enabled swipe gestures for mobile dismissal:

// Built-in on mobile devices
// Swipe left or right to dismiss
// Only works when dismissible: true

API Reference

Toast Props

Prop	Type	Default	Description
`notification`	`Notification`	Required	The notification object to display
`onDismiss`	`(id: string) => void`	-	Callback when toast is dismissed
`onAction`	`(notificationId: string, actionId: string) => void`	-	Callback when action button is clicked
`showProgress`	`boolean`	`true`	Whether to show progress bar
`class`	`string`	`''`	Additional CSS classes

Notification Object

Property	Type	Default	Description
`id`	`string`	Required	Unique identifier
`type`	`'success' \\| 'error' \\| 'warning' \\| 'info'`	Required	Toast type
`title`	`string`	-	Optional title
`message`	`string`	Required	Main message text
`duration`	`number`	`5000`	Auto-dismiss time in ms
`position`	`NotificationPosition`	`'top-right'`	Screen position
`dismissible`	`boolean`	`true`	Can be manually dismissed
`actions`	`NotificationAction[]`	-	Action buttons
`priority`	`number`	`1`	Display priority

useToast() API

Method	Parameters	Description
`success`	`(message: string, options?: Partial<Notification>)`	Show success toast
`error`	`(message: string, options?: Partial<Notification>)`	Show error toast
`warning`	`(message: string, options?: Partial<Notification>)`	Show warning toast
`info`	`(message: string, options?: Partial<Notification>)`	Show info toast
`dismiss`	`(id: string)`	Dismiss specific toast
`dismissAll`	`()`	Dismiss all toasts

Positioning

Toasts can appear in six different positions:

const positions = [
  'top-left',    'top-center',    'top-right',
  'bottom-left', 'bottom-center', 'bottom-right'
];

// Usage
toast.success('Message', { position: 'bottom-center' });

Position Guidelines

top-right: Default, good for most notifications
top-center: Important system messages
bottom-right: Less intrusive for background processes
bottom-center: Mobile-friendly position

Patterns

Form Submission Feedback

<script>
import { enhance } from '$app/forms';
import { useToast } from '$lib/notification/components/use-toast';

const toast = useToast();
</script>

<form
  method="POST"
  use:enhance={({ formData, cancel }) => {
    return async ({ result, update }) => {
      if (result.type === 'success') {
        toast.success('Form submitted successfully');
      } else if (result.type === 'failure') {
        toast.error('Please fix the errors and try again');
      }
      await update();
    };
  }}
>
  <!-- Form fields -->
  <button type="submit">Submit</button>
</form>

API Request Handling

<script>
const toast = useToast();

async function fetchData() {
  toast.info('Loading data...');

  try {
    const response = await fetch('/api/data');

    if (response.ok) {
      toast.success('Data loaded successfully');
    } else {
      toast.error('Failed to load data');
    }
  } catch (error) {
    toast.error('Network error occurred');
  }
}
</script>

Undo Actions

<script>
let items = $state(['Item 1', 'Item 2', 'Item 3']);
const toast = useToast();

function deleteItem(index) {
  const item = items[index];
  items.splice(index, 1);

  toast.info(`Deleted "${item}"`, {
    duration: 8000,
    actions: [
      { id: 'undo', label: 'Undo' }
    ]
  }).then((notification) => {
    // Handle undo if implemented
  });
}
</script>