Toast

Overview

Toast notifications provide lightweight, non-blocking feedback to users. They appear briefly at screen edges and auto-dismiss, perfect for success confirmations, warnings, and informational messages.

Key Features

• Auto-Dismiss - Configurable duration with optional persistence
• Multiple Types - Success, error, warning, info styles
• Positioning - 9 position options (top-left, bottom-right, etc.)
• Queueing - Stack multiple toasts automatically

Basic Usage

Domma.elements.toast('Operation successful!', {
    type: 'success',
    duration: 3000,
    position: 'top-right'
});

Getting Started

Add toast notifications to your page in two simple steps

Step 1: Include Domma

Add Domma CSS and JavaScript to your page:

<!-- CSS -->
<link rel="stylesheet" href="dist/domma.css">
<link rel="stylesheet" href="dist/elements.css">

<!-- JavaScript -->
<script src="dist/domma.min.js"></script>

Step 2: Show Toast Notifications

Call Domma.elements.toast() to display notifications:

// Success notification
Domma.elements.toast('Operation successful!', {
    type: 'success',       // 'success', 'error', 'warning', 'info'
    duration: 3000,        // Auto-dismiss after 3 seconds
    position: 'top-right'  // Position on screen
});

// Error notification
Domma.elements.toast('Something went wrong!', {
    type: 'error',
    duration: 5000
});

// With custom action button
Domma.elements.toast('File uploaded', {
    type: 'info',
    action: 'View',
    onAction: () => {
        console.log('Action clicked');
    }
});

Note: Toast is a static method that auto-generates and positions notification popups (no HTML required). Toasts auto-dismiss after the specified duration and automatically stack if multiple are shown. Supports 9 position options: top-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right.

Quick Start

Simple Toast

<button type="button" id="quick-toast" class="btn btn-primary">Show Toast</button>

/**
 * Simple Toast - from public/showcase/elements/toast.
 */
export function mount(root) {
    $(root).find('#quick-toast').on('click', () => {
        E.toast('Hello, World!', {
            type: 'info',
            duration: 3000
        });
    });
}

$('#btn').on('click', () => {
    Domma.elements.toast('Hello, World!', {
        type: 'info',
        duration: 3000
    });
});

Tutorial

Build a form submission flow with toast notifications.

<div class="forms-max-w-400-center mb-4">
    <div class="form-group mb-3">
        <label>Email</label>
        <input type="email" id="tutorial-email" class="form-input" placeholder="you@example.com">
    </div>
    <div class="form-group mb-3">
        <label>Password</label>
        <input type="password" id="tutorial-password" class="form-input" placeholder="Enter password">
    </div>
    <button type="button" id="tutorial-submit" class="btn btn-primary w-full">Submit</button>
</div>

/**
 * Tutorial - from public/showcase/elements/toast.
 */
export function mount(root) {
        // Tutorial
    $(root).find('#tutorial-submit').on('click', () => {
          const email = $(root).find('#tutorial-email').val();
          const password = $(root).find('#tutorial-password').val();

            if (!email) {
                E.toast('Email is required', {
                    type: 'error',
                    duration: 3000
                });
                return;
            }

            if (password.length < 8) {
                E.toast('Password must be at least 8 characters', {
                    type: 'warning',
                    duration: 4000
                });
                return;
            }

            E.toast('Account created successfully!', {
                type: 'success',
                duration: 5000
            });
        });
}

$('#submit-btn').on('click', () => {
    const email = $('#email').val();
    const password = $('#password').val();

    // Validation with error toast
    if (!email) {
        Domma.elements.toast('Email is required', {
            type: 'error',
            duration: 3000
        });
        return;
    }

    if (password.length < 8) {
        Domma.elements.toast('Password must be at least 8 characters', {
            type: 'warning',
            duration: 4000
        });
        return;
    }

    // Success toast
    Domma.elements.toast('Account created successfully!', {
        type: 'success',
        duration: 5000
    });
});

Examples

Toast Types

<div class="flex gap-2 flex-wrap justify-center">
    <button type="button" id="ex-success" class="btn btn-success">Success</button>
    <button type="button" id="ex-error" class="btn btn-danger">Error</button>
    <button type="button" id="ex-warning" class="btn btn-warning">Warning</button>
    <button type="button" id="ex-info" class="btn btn-secondary">Info</button>
</div>

/**
 * Toast Types - from public/showcase/elements/toast.
 */
export function mount(root) {
        // Toast Types
    $(root).find('#ex-success').on('click', () => {
            E.toast('Operation completed successfully!', {type: 'success'});
        });
    $(root).find('#ex-error').on('click', () => {
            E.toast('An error occurred. Please try again.', {type: 'error'});
        });
    $(root).find('#ex-warning').on('click', () => {
            E.toast('Warning: This action may have consequences.', {type: 'warning'});
        });
    $(root).find('#ex-info').on('click', () => {
            E.toast('For your information: Updates are available.', {type: 'info'});
        });
}

Positioning

<div class="grid gap-2 toast-grid-cols-3-max-w-400 forms-max-w-400-center">
    <button type="button" id="pos-tl" class="btn btn-outline btn-sm">Top Left</button>
    <button type="button" id="pos-tc" class="btn btn-outline btn-sm">Top Center</button>
    <button type="button" id="pos-tr" class="btn btn-outline btn-sm">Top Right</button>
    <button type="button" id="pos-cl" class="btn btn-outline btn-sm">Center Left</button>
    <button type="button" id="pos-cc" class="btn btn-outline btn-sm">Center</button>
    <button type="button" id="pos-cr" class="btn btn-outline btn-sm">Center Right</button>
    <button type="button" id="pos-bl" class="btn btn-outline btn-sm">Bottom Left</button>
    <button type="button" id="pos-bc" class="btn btn-outline btn-sm">Bottom Center</button>
    <button type="button" id="pos-br" class="btn btn-outline btn-sm">Bottom Right</button>
</div>

/**
 * Positioning - from public/showcase/elements/toast.
 */
export function mount(root) {
        // Positioning
    const positions = {
            'pos-tl': 'top-left',
            'pos-tc': 'top-center',
            'pos-tr': 'top-right',
            'pos-cl': 'center-left',
            'pos-cc': 'center',
            'pos-cr': 'center-right',
            'pos-bl': 'bottom-left',
            'pos-bc': 'bottom-center',
            'pos-br': 'bottom-right'
        };
    Object.keys(positions).forEach(id => {
          $('#' + id).on('click', () => {
                E.toast(`Toast at ${positions[id]}`, {
                    position: positions[id],
                    type: 'info'
                });
            });
        });
}

Duration Options

<div class="flex gap-2 justify-center">
    <button type="button" id="dur-short" class="btn btn-outline">Short (1s)</button>
    <button type="button" id="dur-medium" class="btn btn-outline">Medium (3s)</button>
    <button type="button" id="dur-long" class="btn btn-outline">Long (5s)</button>
    <button type="button" id="dur-persist" class="btn btn-outline">Persistent</button>
</div>

/**
 * Duration Options - from public/showcase/elements/toast.
 */
export function mount(root) {
        // Duration
    $(root).find('#dur-short').on('click', () => {
            E.toast('Short duration (1 second)', {duration: 1000});
        });
    $(root).find('#dur-medium').on('click', () => {
            E.toast('Medium duration (3 seconds)', {duration: 3000});
        });
    $(root).find('#dur-long').on('click', () => {
            E.toast('Long duration (5 seconds)', {duration: 5000});
        });
    $(root).find('#dur-persist').on('click', () => {
            E.toast('Persistent toast - click X to close', {
                duration: 0,
                type: 'warning'
            });
        });
}

With Actions

<button type="button" id="ex-action" class="btn btn-primary">Toast with Action</button>

/**
 * With Actions - from public/showcase/elements/toast.
 */
export function mount(root) {
        // Action
    $(root).find('#ex-action').on('click', () => {
            E.toast('File uploaded successfully. Click to view.', {
                type: 'success',
                duration: 5000,
                onClick: () => {
                    E.toast('Navigating to file...');
                }
            });
        });
}

Best Practices

Accessibility

• ARIA Live Regions - Toasts use role="status" and aria-live="polite"
• Avoid Essential Info - Don't put critical information only in toasts
• Dismissible - Provide close button for screen reader users

UX Guidelines

• Appropriate Duration - 3-5 seconds for reading time, longer for actions
• Type Matching - Success for confirmations, error for failures, warning for alerts
• Clear Messages - Concise text (1-2 sentences maximum)
• Limit Stack - Don't overwhelm users with too many simultaneous toasts

Performance

• Auto-Cleanup - Toasts automatically remove themselves from DOM
• Queue Management - System handles multiple toasts efficiently

API Reference

Static Method

Options

Methods

Config Engine

Attach toasts to button clicks using the config engine:

$.setup({
    '#save-btn': {
        events: {
            click: (e, $el) => {
                Domma.elements.toast('Changes saved successfully!', {
                    type: 'success',
                    duration: 3000
                });
            }
        }
    },
    '#delete-btn': {
        events: {
            click: (e, $el) => {
                Domma.elements.toast('Item deleted', {
                    type: 'error',
                    duration: 4000
                });
            }
        }
    }
});

CSS Customisation

Override these CSS variables to customise Toast appearance and match your design system.

Example Override

/* Toast positioning/styling via JavaScript options */

Full CSS Customisation Cheat-Sheet →

Related Elements

<div class="grid grid-cols-1 grid-auto-fit-250 gap-4"><a href="/showcase/elements/dialog" class="card card-hover no-underline text-inherit">
        <div class="card-body">
            <h3 class="card-title">Dialog</h3>
            <p class="card-text">For blocking confirmations and prompts</p>
        </div>
    </a>
    <a href="/showcase/elements/modal" class="card card-hover no-underline text-inherit">
        <div class="card-body">
            <h3 class="card-title">Modal</h3>
            <p class="card-text">For detailed content requiring user focus</p>
        </div>
    </a>
</div>