Skip to main content
The JavaScript API provides a simple toast() function for showing notifications from any client-side code. No Livewire required.

​
Basic usage

Call toast() with a configuration object: 
toast({ type: 'success', title: 'Saved!' });

​
Toast types

Five toast types are available: 
toast({ type: 'success', title: 'Operation complete' });
Green color with smooth slide-up animation.

​
Details and footer

Expand toasts with detail rows and footer text: 
toast({
    type: 'error',
    title: 'Upload failed',
    details: [
        { label: 'File', value: 'report.pdf' },
        { label: 'Error', value: 'File too large' },
    ],
    footer: 'Max file size: 10 MB',
});
Detail rows appear as expandable key-value pairs. The footer displays below the details.

​
Message text

Display a plain text message block instead of structured details: 
toast({
    type: 'info',
    title: 'Melissa',
    avatar: '/avatars/melissa.jpg',
    message: 'Please visit HR when you get a chance 👋',
    footer: '1h ago',
});
Unlike details, the message option renders as natural paragraph text — ideal for chat notifications, alerts, or any freeform content.

​
Action buttons

Add clickable buttons that dispatch custom events: 
toast({
    type: 'success',
    title: 'Message sent',
    actions: [
        { label: 'Undo', icon: 'undo', event: 'undo-send' },
        { label: 'View', icon: 'external-link', event: 'view-message', data: { id: 123 } },
    ],
});

// Listen for the event
window.addEventListener('view-message', (e) => {
    console.log(e.detail); // { id: 123 }
});

​
Button colors

Give individual buttons custom colors: 
toast({
    type: 'info',
    title: 'Incoming call',
    persistent: true,
    actions: [
        { label: 'Accept', icon: 'check', event: 'accept', color: '#22c55e' },
        { label: 'Decline', icon: 'x', event: 'decline', color: '#ef4444' },
    ],
});

​
Confirmation

Require a two-step click with confirm: true: 
toast({
    type: 'warning',
    title: 'Delete account',
    actions: [
        { 
            label: 'Delete', 
            icon: 'trash', 
            event: 'delete-account', 
            color: '#ef4444', 
            confirm: true 
        },
    ],
});
The first click changes the label to “Sure?” for 3 seconds. The event only fires if clicked again.

​
Available icons

Built-in icons you can use in action buttons: external-link, eye, undo, retry, reply, map-pin, download, copy, trash, check, x, image

​
Progress toasts

Show a progress bar that updates as work completes: 
// Create a progress toast — returns an ID
const id = toast.progress('Uploading photos...');

// Update progress (0 to 1)
toast.progress(id, 0.25);
toast.progress(id, 0.5);
toast.progress(id, 0.75);

// Complete — auto-switches to success type
toast.progress(id, 1, 'Upload complete!');
With custom options: 
const id = toast.progress('Processing...', { type: 'warning', color: '#8b5cf6' });

​
Undo toasts

Show a countdown with an inline undo button: 
toast.undo('Message deleted', 'confirm-delete', { id: 123 });

// Listen — only fires if NOT undone
window.addEventListener('confirm-delete', (e) => {
    fetch(`/api/messages/${e.detail.id}`, { method: 'DELETE' });
});
With full options: 
toast.undo({
    title: 'Item archived',
    event: 'confirm-archive',      // fires on countdown expiry
    undoEvent: 'undo-archive',     // fires if user clicks undo (optional)
    data: { id: 456 },
    duration: 8000,                // countdown length in ms
    type: 'info',                  // toast type (default: warning)
});

​
Promise toasts

Show a loading spinner that resolves to success or error automatically: 
toast.promise(fetch('/api/save'), {
    loading: 'Saving...',
    success: 'Saved!',
    error: 'Failed to save',
});
Returns the original promise so you can chain .then().

​
Persistent toasts

Prevent auto-dismissal: 
toast({ type: 'error', title: 'Connection lost', persistent: true });
Persistent toasts only close via the close button, an action button, or swipe gesture.

​
Custom colors

Override the type color: 
toast({ type: 'success', title: 'VIP Access Granted', color: '#8b5cf6' });
Works with all toast types: 
toast.undo('Archived', 'confirm-archive', { id: 1 });
toast.progress('Syncing...', { color: '#ec4899' });
toast({ type: 'info', title: 'Custom', color: '#06b6d4', persistent: true });

​
User avatars

Display an avatar image instead of the type icon: 
toast({
    title: 'New message from John',
    avatar: '/avatars/john.jpg',
    type: 'info'
});
Custom avatar size: 
toast({
    title: 'Welcome back!',
    avatar: '/avatars/user.png',
    avatarSize: '32px',
    type: 'success'
});

​
Vibration

Trigger device vibration (mobile only): 
// Simple vibration (200ms)
toast({ type: 'info', title: 'Alert!', vibrate: true });

// Custom pattern (vibrate, pause, vibrate)
toast({ type: 'info', title: 'Incoming call', vibrate: [200, 100, 200] });
Uses the Vibration API — silently ignored on desktop browsers.

​
Updating toasts

Update any toast by ID: 
toast.update('my-toast', { title: 'New title', type: 'success' });
You can update the title, type, progress, and other properties after the toast is displayed.

​
Theme switching

Switch between dark and light themes at runtime: 
toast.theme('light');
toast.theme('dark');

​
Custom icons

Register your own SVG icons: 
toast.registerIcon('star', '<svg viewBox="0 0 24 24">...</svg>');

// Use in toasts
toast({ type: 'success', title: 'Favorited!', icon: 'star' });

​
Full options reference

toast({
    type: 'success',             // success, error, warning, info, loading
    title: 'Notification',       // required
    id: 'my-id',                 // optional — use for updates
    message: 'Text block',      // optional — plain text message
    avatar: '/path/to/image.jpg', // optional — avatar image URL
    avatarSize: '32px',         // optional — avatar size (default: 18px)
    details: [                   // optional — expandable rows
        { label: 'Key', value: 'Value' },
    ],
    footer: 'Footer text',      // optional
    actions: [                   // optional — buttons in expanded body
        { 
            label: 'Click me', 
            icon: 'check', 
            event: 'my-event', 
            data: {}, 
            color: '#22c55e', 
            confirm: false 
        },
    ],
    duration: 5000,              // optional — override config duration
    persistent: false,           // optional — never auto-dismiss
    color: '#8b5cf6',            // optional — override type color
    progress: 0.5,              // optional — show progress bar (0 to 1)
    icon: 'star',                // optional — override type icon (registered name)
    vibrate: true,               // optional — vibrate on mobile (true or [ms] pattern)
});

Build docs developers (and LLMs) love

Get started for freeTalk to us