README

A simple, global and non-intrusive progress bar system for Filament.

This package allows you to track long-running processes (jobs, imports, exports, background tasks) and display their progress globally in the Filament admin panel, without wiring Livewire components or custom widgets per page.

It is designed to be:

• Simple (explicit API: init → update → complete)
• Safe for queued jobs
• Cache-based (Redis optional, not required)
• Filament-native (top bar overlay, polling handled automatically)

Features

• Global progress bar overlay in Filament
• Multiple simultaneous progress bars
• Determinate and indeterminate progress
• Auto-polling only when progress bars are active
• Safe default behaviour for queued jobs
• No Redis requirement (uses Laravel cache)
• Redis-ready if you want it later

Installation

Install the package via Composer:

composer require marceloanjosdev/filament-progress-bar

Publish the configuration file:

php artisan vendor:publish --tag="filament-progress-bar-config"

No migrations are required.

Configuration

This is the default configuration file:

return [
    'cache_store' => null,

    'key_prefix' => 'filament-progress-bar',

    'ttl_seconds' => 3600,

    'display' => [
        /*
         | Available options:
         | - 'percent'  → 75%
         | - 'total'    → 75/100
         | - 'both'     → 75/100 · 75%
         */
        'meta' => 'both',
    ],

    'polling' => [
        'enabled' => true,

        // When there are no bars
        'idle_interval_ms' => 5000,

        // When there is at least one bar
        'active_interval_ms' => 1000,

        // Route & middleware for the internal endpoint used by the Filament UI
        'route' => '/filament-progress-bar/progress',
        'middleware' => ['web', 'auth'],
    ],
];

Usage

   app(ProgressManager::class)->init(
       key: 'progress:one',
       totalRecords: 100,
       autoComplete: true,
       label: 'Import Clients'
    );

    app(ProgressManager::class)->update('progress:one');

    app(ProgressManager::class)->complete('progress:one');

Testing

composer test

License

MIT License.