README

Flare

Production-Ready Toast Notifications for Laravel Livewire

Elegant • Performant • Customizable

Features • Installation • Quick Start • Documentation • Themes • Examples

🎯 Overview

Flare is a modern, feature-rich toast notification system built specifically for Laravel Livewire applications. With zero configuration required and three distinct visual themes, Flare provides beautiful user feedback out of the box while offering extensive customization for advanced use cases.

// Simple, elegant API
Flare::success('Profile updated successfully!');

// Full control when you need it
Flare::warning(
    text: 'Session expires in 5 minutes',
    heading: 'Warning',
    duration: 10000,
    position: 'top center'
);

✨ Features

🎨 Three Professional Themes

Classic - Minimal, clean, fastest performance
Modern - Balanced design with subtle effects (default)
Vibrant - Bold, colorful, attention-grabbing

All themes include:

✓ Light & dark mode support
✓ Smooth animations
✓ Responsive design
✓ RTL/LTR layouts

⚡ High Performance

Alpine.js powered (minimal overhead)
Optimized CSS transitions
Smart caching & compilation
No jQuery dependency
Lightweight footprint (~15KB)

🔧 Developer Experience

Zero Configuration - Works out of the box
Simple API - Intuitive, clean methods
Livewire Trait - use WithFlare
TypeScript Support - Full type definitions
IDE Autocomplete - PHPDoc annotations

📍 Flexible Positioning

6 position options (top/bottom × start/center/end)
Per-toast position override
RTL/LTR automatic adaptation
Responsive mobile behavior

🎭 Advanced Features

Stacking System - Configurable toast layering
Auto-Dismiss - Configurable duration
Hover Pause - Pause on mouse hover
Keyboard Shortcuts - Esc, Shift+Esc, Alt+D
Progress Bar - Visual countdown
Queue Management - Handle multiple toasts

🧪 Production Ready

✓ Comprehensive test suite (12 tests, 22 assertions)
✓ PHPStan Level 9 compliance
✓ PSR-12 code style
✓ CI/CD with GitHub Actions
✓ Semantic versioning
✓ Extensive documentation

📋 Requirements

Requirement	Version
PHP	8.3+
Laravel	12.0+
Livewire	3.5+
Alpine.js	3.x (included in Livewire 3)

🚀 Installation

Step 1: Install via Composer

composer require alizharb/flare

Step 2: Publish Assets

IMPORTANT: Assets must be published for Flare to work.

php artisan vendor:publish --tag=flare-assets

Step 3: Add to Layout

<!DOCTYPE html>
<html lang="en">
<head>
    @flareStyles {{-- Required --}}
</head>
<body>
    <flare::toasts /> {{-- Required --}}

    @flareScripts {{-- Required --}}
</body>
</html>

That's it! 🎉 You're ready to use Flare.

Optional Configuration

# Publish config file
php artisan vendor:publish --tag=flare-config

# Publish views for customization
php artisan vendor:publish --tag=flare-views

⚡ Quick Start

Using the Facade

Perfect for controllers, services, and any PHP class:

use AlizHarb\Flare\Facades\Flare;

class UserController extends Controller
{
    public function store(Request $request)
    {
        User::create($request->validated());

        Flare::success('User created successfully!');

        return redirect()->route('users.index');
    }
}

Using the Livewire Trait

The easiest way in Livewire components:

use Livewire\Component;
use AlizHarb\Flare\Concerns\WithFlare;

class CreatePost extends Component
{
    use WithFlare;

    public function save()
    {
        Post::create($this->validate());

        $this->flareSuccess('Post published!', 'Success');
    }
}

Using JavaScript

For client-side notifications:

// Simple
Flare.success("Item added to cart!");

// Advanced
Flare.toast("Welcome back!", {
  heading: "Hello User",
  variant: "info",
  duration: 5000,
  position: "top center",
});

🎨 Themes

Flare includes three professionally designed themes. Choose the one that fits your application's aesthetic.

Classic

Minimal & Professional

Solid backgrounds
Single shadow
No blur
⚡ Fastest

'theme' => 'classic'

Modern

Balanced & Contemporary

Subtle gradients
Light blur (4px)
2 shadow layers
⚡ Fast (default)

'theme' => 'modern'

Vibrant

Bold & Colorful

Strong gradients
Glowing shadows
Moderate blur (8px)
⚡ Good

'theme' => 'vibrant'

All themes support light & dark modes automatically.

📚 Documentation

📖 Complete Documentation

Visit our comprehensive documentation:

Introduction - What is Flare?
Installation - Detailed setup guide
Quick Start - Get started in 5 minutes
Themes - Visual customization
Configuration - All options explained
Examples - Real-world scenarios

🌐 Interactive Docs

Run the documentation website locally:

php -S localhost:8000 -t docs

Visit http://localhost:8000 for interactive documentation.

💡 API Reference

Toast Variants

Flare::success($text, $heading = null, $duration = 5000, $position = null);
Flare::warning($text, $heading = null, $duration = 5000, $position = null);
Flare::danger($text, $heading = null, $duration = 5000, $position = null);
Flare::error($text, $heading = null, $duration = 5000, $position = null); // Alias
Flare::info($text, $heading = null, $duration = 5000, $position = null);

Livewire Trait Methods

$this->flareSuccess($text, $heading = null, $duration = 5000, $position = null);
$this->flareWarning($text, $heading = null, $duration = 5000, $position = null);
$this->flareDanger($text, $heading = null, $duration = 5000, $position = null);
$this->flareError($text, $heading = null, $duration = 5000, $position = null);
$this->flareInfo($text, $heading = null, $duration = 5000, $position = null);

JavaScript API

Flare.toast(text, options);
Flare.success(text, options);
Flare.warning(text, options);
Flare.danger(text, options);
Flare.error(text, options);
Flare.info(text, options);

⚙️ Configuration

View Complete Configuration

return [
    // Visual theme
    'theme' => 'modern', // classic, modern, vibrant

    // Default position
    'position' => 'bottom end',

    // Default duration (ms)
    'duration' => 5000,

    // Stacking behavior
    'enable_stacking' => true,
    'stack_expanded' => false,
    'max_visible' => 3,

    // Features
    'icons' => ['enabled' => true],
    'actions' => ['enabled' => true],
    'priority' => ['enabled' => true],
    'rate_limit' => ['enabled' => true],
    'progress_bar' => ['enabled' => true],
];

Environment Variables

FLARE_THEME=modern
FLARE_POSITION="bottom end"
FLARE_DURATION=5000
FLARE_ENABLE_STACKING=true
FLARE_STACK_EXPANDED=false

🎯 Examples

Form Validation

class ContactForm extends Component
{
    use WithFlare;

    public function submit()
    {
        $this->validate([...]);

        // Send email...

        $this->flareSuccess(
            text: "Thank you! We'll get back to you soon.",
            heading: 'Message Sent',
            duration: 7000
        );
    }
}

CRUD Operations

public function destroy(Post $post)
{
    $post->delete();

    Flare::danger(
        text: 'Post has been permanently deleted',
        heading: 'Deleted',
        duration: 4000
    );

    return redirect()->route('posts.index');
}

Persistent Notifications

// Requires manual dismissal
Flare::danger(
    text: 'Critical error - please contact support',
    heading: 'Error',
    duration: 0 // Never auto-dismiss
);

See EXAMPLES.md for more real-world scenarios.

⌨️ Keyboard Shortcuts

Shortcut	Action
`Esc`	Dismiss most recent toast
`Shift + Esc`	Dismiss all toasts
`Alt + D`	Dismiss all toasts (alternative)

🧪 Testing

Flare includes a comprehensive test suite:

# Run tests
composer test

# Run tests with coverage
composer test:coverage

# Run static analysis
composer analyse

# Run code style fixer
composer format

Test Results: ✅ 12 tests, 22 assertions, 100% passing

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

git clone https://github.com/alizharb/flare.git
cd flare
composer install
composer test

📝 Changelog

See CHANGELOG.md for all changes and version history.

Latest Release: v1.1.0

✨ Three distinct themes (Classic, Modern, Vibrant)
🐛 Fixed all positioning issues
⚡ Improved stacking performance
🌍 Added RTL/LTR support
📚 Complete documentation

📄 License

Flare is open-source software licensed under the MIT License.

🙏 Credits

Built with ❤️ by Ali Harb

Special thanks to:

Laravel & Livewire teams
Alpine.js community
All contributors

🌟 Support

If you find Flare useful, please consider:

⭐ Starring the repository
🐛 Reporting bugs
💡 Suggesting features
📖 Improving documentation
💰 Sponsoring development

⬆ Back to Top

Made with ❤️ for the Laravel community

alizharb / flare

Maintainers

Details