āœØ LucidAlerts

A beautiful, modern alert & notification library with smooth animations, clean design, and built-in dark mode support. Experience the next generation of user notifications with comprehensive examples and integration guides.

šŸŽØ Theme Controls

šŸ“¢ Basic Alerts

Simple alert dialogs with different types and styling.

šŸš€ Advanced Alerts

Alerts with custom options, timers, and callbacks.

šŸ“ Form Alerts

Interactive alerts with input fields and forms.

šŸ”” Notifications

Toast notifications with different positions and types.

šŸ› ļø Utility Functions

Management and utility functions for alerts and notifications.

šŸŽØ Theme Demo

Test alerts and notifications in different themes.

šŸ“ Basic Usage Examples

Simple examples to get you started with LucidAlerts.

Basic Alerts 
// Basic success alert
LucidAlerts.success('Operation completed successfully!');

// Error alert with title
LucidAlerts.error({
    title: 'Error!',
    text: 'Something went wrong. Please try again.'
});

// Warning with timer
LucidAlerts.warning({
    title: 'Warning',
    text: 'This will auto-close in 3 seconds',
    timer: 3000
});

// Info alert
LucidAlerts.info('Here is some important information.');

// Question/Confirmation
LucidAlerts.question('Are you sure you want to delete this item?')
    .then(result => {
        if (result) {
            console.log('User confirmed');
        }
    });

šŸ”” Notification Examples

Toast notifications with various configurations.

Notifications 
// Basic notification
LucidAlerts.notify({
    type: 'success',
    message: 'File uploaded successfully!'
});

// Notification with custom position
LucidAlerts.notify({
    type: 'info',
    title: 'New Message',
    message: 'You have received a new message.',
    position: 'top-right',
    duration: 5000
});

// Notification with progress bar
LucidAlerts.notify({
    type: 'info',
    title: 'Uploading...',
    message: 'Please wait while we upload your file.',
    position: 'bottom-right',
    showProgress: true,
    duration: 10000
});

// Persistent notification (no auto-close)
LucidAlerts.notify({
    type: 'warning',
    title: 'Important Notice',
    message: 'Please update your password.',
    position: 'top-center',
    persistent: true
});

šŸ“ Form Input Examples

Interactive alerts with form inputs.

Form Inputs 
// Simple text input
LucidAlerts.input({
    title: 'Enter Your Name',
    placeholder: 'Your name here...',
    confirmText: 'Submit'
}).then(result => {
    if (result.isConfirmed) {
        console.log('Name:', result.value);
    }
});

// Select dropdown
LucidAlerts.select({
    title: 'Choose Your Country',
    options: [
        { value: 'us', text: 'United States' },
        { value: 'uk', text: 'United Kingdom' },
        { value: 'ca', text: 'Canada' }
    ]
}).then(result => {
    if (result.isConfirmed) {
        console.log('Selected:', result.value);
    }
});

// Multiple inputs
LucidAlerts.form({
    title: 'User Registration',
    inputs: [
        { name: 'username', type: 'text', placeholder: 'Username' },
        { name: 'email', type: 'email', placeholder: 'Email' },
        { name: 'password', type: 'password', placeholder: 'Password' }
    ]
}).then(result => {
    if (result.isConfirmed) {
        console.log('Form data:', result.values);
    }
});

šŸŽØ Advanced Customization

Advanced options and customization examples.

Advanced Options 
// Custom styled alert
LucidAlerts.success({
    title: 'Custom Alert',
    text: 'This alert has custom styling',
    confirmText: 'Awesome!',
    cancelText: 'Maybe Later',
    showCancel: true,
    customClass: 'my-custom-alert'
});

// Alert with callback
LucidAlerts.question('Delete this item?')
    .then(result => {
        if (result) {
            return LucidAlerts.success('Item deleted!');
        } else {
            return LucidAlerts.info('Deletion cancelled');
        }
    });

// Theme management
LucidAlerts.setTheme('dark');  // Set dark theme
LucidAlerts.setTheme('light'); // Set light theme
LucidAlerts.setTheme('auto');  // Auto theme (follows system)

// Utility functions
console.log('Active alerts:', LucidAlerts.activeAlerts.size);
console.log('Active notifications:', LucidAlerts.activeNotifications.size);

// Close all alerts and notifications
LucidAlerts.closeAll();

šŸ”§ Integration Guide

Learn how to integrate LucidAlerts into your application with these comprehensive guides.

šŸ“¦ Installation

NPM Installation 
npm install lucid-alerts
CDN Installation 
<!-- Latest version -->
<script src="https://cdn.jsdelivr.net/npm/lucid-alerts@latest/dist/lucid-alerts.min.js"></script>

<!-- Specific version (v1.1.3) -->
<script src="https://cdn.jsdelivr.net/npm/lucid-alerts@1.1.3/dist/lucid-alerts.min.js"></script>

šŸš€ Quick Start

ES6 Modules 
import LucidAlerts from 'lucid-alerts';

// Show a success alert
LucidAlerts.success('Welcome to your application!');
CommonJS 
const LucidAlerts = require('lucid-alerts');

// Show a success alert
LucidAlerts.success('Welcome to your application!');
Browser Script Tag 
<!DOCTYPE html>
<html>
<head>
    <title>My App</title>
</head>
<body>
    <script src="path/to/lucid-alerts.min.js"></script>
    <script>
        // LucidAlerts is now available globally
        LucidAlerts.success('Hello World!');
    </script>
</body>
</html>

āš›ļø React Integration

React Component 
import React from 'react';
import LucidAlerts from 'lucid-alerts';

function MyComponent() {
    const handleSuccess = () => {
        LucidAlerts.success('Operation completed!');
    };

    const handleConfirm = async () => {
        const result = await LucidAlerts.question('Are you sure?');
        if (result) {
            // User confirmed
            console.log('Confirmed!');
        }
    };

    return (
        <div>
            <button onClick={handleSuccess}>Show Success</button>
            <button onClick={handleConfirm}>Confirm Action</button>
        </div>
    );
}

export default MyComponent;

šŸ…°ļø Angular Integration

Angular Service 
import { Injectable } from '@angular/core';
import LucidAlerts from 'lucid-alerts';

@Injectable({
    providedIn: 'root'
})
export class AlertService {
    
    success(message: string, title?: string) {
        return LucidAlerts.success({ title, text: message });
    }

    error(message: string, title?: string) {
        return LucidAlerts.error({ title, text: message });
    }

    confirm(message: string, title?: string): Promise<boolean> {
        return LucidAlerts.question({ title, text: message });
    }

    notify(type: string, message: string, position?: string) {
        return LucidAlerts.notify({
            type,
            message,
            position: position || 'top-right'
        });
    }
}
Angular Component Usage 
import { Component } from '@angular/core';
import { AlertService } from './alert.service';

@Component({
    selector: 'app-my-component',
    template: `
        <button (click)="showSuccess()">Success</button>
        <button (click)="confirmDelete()">Delete</button>
    `
})
export class MyComponent {
    
    constructor(private alertService: AlertService) {}

    showSuccess() {
        this.alertService.success('Operation completed!', 'Success');
    }

    async confirmDelete() {
        const confirmed = await this.alertService.confirm(
            'This action cannot be undone.',
            'Delete Item'
        );
        
        if (confirmed) {
            // Proceed with deletion
            this.alertService.success('Item deleted successfully!');
        }
    }
}

šŸ’š Vue.js Integration

Vue Plugin 
// plugins/lucid-alerts.js
import LucidAlerts from 'lucid-alerts';

export default {
    install(app) {
        app.config.globalProperties.$alerts = LucidAlerts;
        app.provide('alerts', LucidAlerts);
    }
};

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import LucidAlertsPlugin from './plugins/lucid-alerts';

const app = createApp(App);
app.use(LucidAlertsPlugin);
app.mount('#app');
Vue Component Usage 
<template>
    <div>
        <button @click="showSuccess">Success</button>
        <button @click="confirmAction">Confirm</button>
    </div>
</template>

<script>
import { inject } from 'vue';

export default {
    setup() {
        const alerts = inject('alerts');

        const showSuccess = () => {
            alerts.success('Operation completed!');
        };

        const confirmAction = async () => {
            const result = await alerts.question('Are you sure?');
            if (result) {
                alerts.success('Action confirmed!');
            }
        };

        return {
            showSuccess,
            confirmAction
        };
    }
};
</script>

šŸŽØ Theming & Customization

LucidAlerts supports automatic dark mode detection and manual theme switching.

Theme Management 
// Set theme manually
LucidAlerts.setTheme('dark');   // Force dark theme
LucidAlerts.setTheme('light');  // Force light theme
LucidAlerts.setTheme('auto');   // Follow system preference

// Custom CSS classes
LucidAlerts.success({
    title: 'Custom Styled Alert',
    text: 'This alert has custom styling',
    customClass: 'my-custom-alert'
});

// CSS for custom styling
/*
.my-custom-alert {
    border: 2px solid #10b981;
    background: linear-gradient(135deg, #ecfdf5, #d1fae5);
}
*/

šŸ“± Best Practices

  • Use appropriate alert types: Success for confirmations, Error for failures, Warning for cautions, Info for general messages.
  • Keep messages concise: Users should be able to quickly understand the message.
  • Use timers wisely: Auto-close success messages, but let users dismiss errors manually.
  • Position notifications appropriately: Top-right for general notifications, center for important alerts.
  • Handle promises: Always handle the promise returned by confirmation dialogs.
  • Respect user preferences: Use auto theme to respect system dark mode settings.
  • Test across devices: Ensure alerts work well on mobile and desktop.

šŸ”§ Configuration Options

All available configuration options for alerts and notifications:

Configuration Reference 
// Alert options
const alertOptions = {
    title: 'Alert Title',           // Alert title
    text: 'Alert message',          // Alert message
    type: 'success',                // success, error, warning, info, question
    confirmText: 'OK',              // Confirm button text
    cancelText: 'Cancel',           // Cancel button text
    showCancel: false,              // Show cancel button
    timer: 0,                       // Auto-close timer (ms)
    customClass: '',                // Custom CSS class
    allowOutsideClick: true,        // Close on outside click
    allowEscapeKey: true            // Close on escape key
};

// Notification options
const notificationOptions = {
    type: 'info',                   // success, error, warning, info
    title: 'Notification Title',    // Notification title
    message: 'Notification text',   // Notification message
    position: 'top-right',          // Position on screen
    duration: 5000,                 // Auto-close duration (ms)
    persistent: false,              // Don't auto-close
    showProgress: false,            // Show progress bar
    allowClose: true,               // Show close button
    customClass: ''                 // Custom CSS class
};

// Form input options
const inputOptions = {
    title: 'Input Title',           // Form title
    placeholder: 'Enter value...',  // Input placeholder
    value: '',                      // Default value
    type: 'text',                   // Input type
    required: false,                // Required field
    confirmText: 'Submit',          // Submit button text
    cancelText: 'Cancel'            // Cancel button text
};

šŸ“š API Reference

Complete API documentation for all LucidAlerts methods and options.

šŸŽÆ Core Methods

Basic Alert Methods 
// Basic alert methods
LucidAlerts.success(message)           // Success alert
LucidAlerts.error(message)             // Error alert  
LucidAlerts.warning(message)           // Warning alert
LucidAlerts.info(message)              // Info alert
LucidAlerts.question(message)          // Question/confirmation alert

// Advanced alert method
LucidAlerts.alert(options)             // Custom alert with full options

// All methods can accept either a string or options object:
LucidAlerts.success('Simple message');
LucidAlerts.success({
    title: 'Success!',
    text: 'Operation completed',
    timer: 3000
});
Notification Methods 
// Notification method
LucidAlerts.notify(options)

// Examples:
LucidAlerts.notify({
    type: 'success',
    message: 'File uploaded successfully!'
});

LucidAlerts.notify({
    type: 'error',
    title: 'Upload Failed',
    message: 'Please try again later.',
    position: 'top-center',
    persistent: true
});
Form Input Methods 
// Input methods
LucidAlerts.input(options)             // Single text input
LucidAlerts.select(options)            // Select dropdown
LucidAlerts.form(options)              // Multiple inputs

// Examples:
const result = await LucidAlerts.input({
    title: 'Enter your name',
    placeholder: 'Your name...'
});

const selection = await LucidAlerts.select({
    title: 'Choose option',
    options: [
        { value: '1', text: 'Option 1' },
        { value: '2', text: 'Option 2' }
    ]
});

const formData = await LucidAlerts.form({
    title: 'User Details',
    inputs: [
        { name: 'name', type: 'text', placeholder: 'Name' },
        { name: 'email', type: 'email', placeholder: 'Email' }
    ]
});

šŸ› ļø Utility Methods

Utility Functions 
// Theme management
LucidAlerts.setTheme(theme)            // 'light', 'dark', or 'auto'
LucidAlerts.getTheme()                 // Get current theme

// Alert management
LucidAlerts.closeAll()                 // Close all alerts and notifications
LucidAlerts.activeAlerts               // Set of active alerts
LucidAlerts.activeNotifications        // Set of active notifications

// Examples:
console.log('Active alerts:', LucidAlerts.activeAlerts.size);
console.log('Active notifications:', LucidAlerts.activeNotifications.size);

// Close everything
LucidAlerts.closeAll();

šŸ“‹ Options Reference

Alert Options 
const alertOptions = {
    // Content
    title: string,                     // Alert title
    text: string,                      // Alert message
    type: string,                      // 'success', 'error', 'warning', 'info', 'question'
    
    // Buttons
    confirmText: string,               // Confirm button text (default: 'OK')
    cancelText: string,                // Cancel button text (default: 'Cancel')
    showCancel: boolean,               // Show cancel button (default: false)
    
    // Behavior
    timer: number,                     // Auto-close timer in ms (default: 0 = no timer)
    allowOutsideClick: boolean,        // Close on outside click (default: true)
    allowEscapeKey: boolean,           // Close on escape key (default: true)
    
    // Styling
    customClass: string                // Custom CSS class name
};
Notification Options 
const notificationOptions = {
    // Content
    type: string,                      // 'success', 'error', 'warning', 'info'
    title: string,                     // Notification title (optional)
    message: string,                   // Notification message
    
    // Position
    position: string,                  // 'top-left', 'top-center', 'top-right',
                                      // 'bottom-left', 'bottom-center', 'bottom-right'
    
    // Behavior
    duration: number,                  // Auto-close duration in ms (default: 5000)
    persistent: boolean,               // Don't auto-close (default: false)
    allowClose: boolean,               // Show close button (default: true)
    
    // Features
    showProgress: boolean,             // Show progress bar (default: false)
    
    // Styling
    customClass: string                // Custom CSS class name
};
Form Input Options 
// Single input options
const inputOptions = {
    title: string,                     // Form title
    placeholder: string,               // Input placeholder
    value: string,                     // Default value
    type: string,                      // 'text', 'email', 'password', 'number', etc.
    required: boolean,                 // Required field (default: false)
    confirmText: string,               // Submit button text (default: 'Submit')
    cancelText: string                 // Cancel button text (default: 'Cancel')
};

// Select options
const selectOptions = {
    title: string,                     // Form title
    options: Array,                    // Array of {value, text} objects
    confirmText: string,               // Submit button text
    cancelText: string                 // Cancel button text
};

// Multi-input form options
const formOptions = {
    title: string,                     // Form title
    inputs: Array,                     // Array of input configurations
    confirmText: string,               // Submit button text
    cancelText: string                 // Cancel button text
};

// Input configuration for forms
const inputConfig = {
    name: string,                      // Input name (for form data)
    type: string,                      // Input type
    placeholder: string,               // Input placeholder
    value: string,                     // Default value
    required: boolean                  // Required field
};

šŸ”„ Return Values

Promise Return Values 
// Alert methods return promises that resolve to:
// - true if confirmed
// - false if cancelled or dismissed

const result = await LucidAlerts.question('Delete item?');
if (result) {
    console.log('User confirmed');
} else {
    console.log('User cancelled');
}

// Input methods return objects with:
const inputResult = await LucidAlerts.input('Enter name:');
// {
//     isConfirmed: boolean,    // true if submitted, false if cancelled
//     value: string           // the input value (if confirmed)
// }

// Form methods return objects with:
const formResult = await LucidAlerts.form({...});
// {
//     isConfirmed: boolean,    // true if submitted, false if cancelled
//     values: object          // object with input names as keys
// }

// Example form result:
// {
//     isConfirmed: true,
//     values: {
//         name: 'John Doe',
//         email: 'john@example.com'
//     }
// }

šŸŽØ CSS Classes

Available CSS classes for customization:

CSS Class Reference 
/* Alert classes */
.lucid-backdrop                        /* Alert backdrop/overlay */
.lucid-alert                          /* Alert container */
.lucid-alert.success                  /* Success alert */
.lucid-alert.error                    /* Error alert */
.lucid-alert.warning                  /* Warning alert */
.lucid-alert.info                     /* Info alert */
.lucid-alert.question                 /* Question alert */

/* Notification classes */
.lucid-notifications                  /* Notification container */
.lucid-notification                   /* Individual notification */
.lucid-notification.success           /* Success notification */
.lucid-notification.error             /* Error notification */
.lucid-notification.warning           /* Warning notification */
.lucid-notification.info              /* Info notification */

/* Form classes */
.lucid-form                          /* Form container */
.lucid-input                         /* Form inputs */
.lucid-select                        /* Select dropdowns */

/* Button classes */
.lucid-button                        /* Alert buttons */
.lucid-button.primary                /* Primary button */
.lucid-button.secondary              /* Secondary button */

/* Theme classes */
[data-theme="light"]                 /* Light theme */
[data-theme="dark"]                  /* Dark theme */