README

بسم الله والحمد لله والصلاة والصلام على رسول الله وعلى آله وصحبه

Filament PopupModal

A comprehensive modal dialog system for FilamentPHP with real-time progress bars, callbacks, and full theme integration.

Features

• 🎨 Full Filament Theme Integration - Uses native Filament components and colors
• 📊 Real-time Progress Bars - Smooth animations with theme-aware styling
• 🔔 Callback Support - Execute functions on confirm/close actions
• 🖼️ Icon Customization - Adjustable icon sizes (sm, md, lg) with auto-icons
• 🌙 Dark Mode Support - Automatically adapts to Filament's theme
• 📱 Responsive Design - Works perfectly on all screen sizes
• ⚡ Performance Optimized - Lightweight Livewire-based implementation
• 🎯 Fluent API - Intuitive method chaining for easy usage

Installation

You can install the package via composer:

composer require maystro/filament-popup-modal

The package will automatically register itself via Laravel's package discovery.

Optionally, you can publish the config file:

php artisan vendor:publish --tag="popup-modal-config"

Optionally, you can publish the views:

php artisan vendor:publish --tag="popup-modal-views"

Usage

Basic Modal

use Maystro\FilamentPopupModal\PopupModal;
use Maystro\FilamentPopupModal\Enums\Colors;

PopupModal::make()
    ->title('Success!')
    ->body('Operation completed successfully.')
    ->color(Colors::Success)
    ->show();

Progress Modal

// Create progress modal
$modal = PopupModal::progressModal(
    'Processing Data',
    'Please wait while we process your data...',
    Colors::Primary
);

$modal->show();

// Update progress
$modal->updateProgress(50);

Modal with Callbacks

PopupModal::make()
    ->title('Confirm Action')
    ->body('Are you sure you want to proceed?')
    ->color(Colors::Warning)
    ->confirm(true)
    ->onConfirm(function () {
        // Your action here
        Notification::make()->title('Confirmed!')->success()->send();
    })
    ->show();

Icon Sizing

PopupModal::make()
    ->title('Important Notice')
    ->body('This is an important message.')
    ->icon('heroicon-o-exclamation-triangle')
    ->iconSize('lg')  // sm, md, lg
    ->color(Colors::Warning)
    ->show();

Using Helper Functions

// Quick popup
show_popup('Hello', 'This is a quick popup!', Colors::Info);

// Progress popup
$modal = show_progress_popup('Processing...', 'Please wait...');
update_popup_progress($modal->getData()['id'], 75);

Using Facade

Add to your config/app.php:

'aliases' => [
    // ... other aliases
    'PopupModal' => Maystro\FilamentPopupModal\Facades\PopupModal::class,
],

Then use:

PopupModal::make()->title('Hello')->show();

API Reference

Methods

Static Methods

PopupModal::progressModal($title, $body, $color)  // Create progress modal
PopupModal::updateProgressById($id, $percent)     // Update any modal's progress

Helper Functions

popup_modal($id)                                  // Create instance
show_popup($title, $body, $color, $icon)        // Quick popup
show_progress_popup($title, $body, $color)      // Progress popup
update_popup_progress($modalId, $percent)        // Update progress

Color System

The package uses Filament's standardized color palette:

Colors::Primary    // Main brand color
Colors::Secondary  // Secondary accent
Colors::Success    // Green success states
Colors::Warning    // Orange warning states  
Colors::Danger     // Red error states
Colors::Info       // Blue informational
Colors::Gray       // Neutral gray

Configuration

The config file allows you to customize default values:

return [
    'default_confirm_label' => 'Confirm',
    'default_close_label' => 'Close',
    
    'progress' => [
        'default_color' => 'primary',
        'update_interval' => 500,
        'completion_delay' => 1500,
    ],
    
    'modal' => [
        'default_width' => 'lg',
        'default_color' => 'info',
        'default_icon_size' => 'md',
        'auto_register' => true,
    ],
    
    'icons' => [
        'auto_assign' => true,
        'fallback_icon' => 'heroicon-o-information-circle',
    ],
];

Requirements

• Laravel 12.x
• FilamentPHP 3.x
• Livewire 3.x
• PHP 8.1+

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Maystro
• All Contributors

License

The MIT License (MIT). Please see License File for more information.