Progress Bar

ProgressBarModule renders a server-driven progress indicator for long-running admin tasks. Adminix calls the handler during page generation, so the first HTML render already contains the current status, percent, and optional absolute values without waiting for a browser polling request. It does not poll while inactive.

use AlexKudrya\Adminix\Modules\Module;
use AlexKudrya\Adminix\Modules\List\BulkAction;
use AlexKudrya\Adminix\Enums\ColorsEnum;
use App\Adminix\Progress\ImportProgressHandler;
use App\Adminix\Actions\StartImportAction;

Module::progressBar()
    ->name('import-progress')
    ->title('Import progress')
    ->handler(ImportProgressHandler::class)
    ->pollIntervalSeconds(3)
    ->showValues()
    ->color(ColorsEnum::SEA_GREEN);

Module::link()
    ->name('start-import')
    ->title('Start import')
    ->uri('admin.import.start')
    ->progressTrigger('import-progress');

BulkAction::make('start-import')
    ->title('Start import')
    ->queued('Import queued.')
    ->progressTrigger('import-progress')
    ->handler(StartImportAction::class);

The trigger is isolated from the button action. A link, submit button, modal toggler, or custom element can keep its own behavior and also start the progress bar by rendering data-adminix-progress-trigger="import-progress". Built-in LinkModule, ModalTogglerModule, and BulkAction expose this as progressTrigger('import-progress'). Adminix does not prevent the button's default action; if the click navigates away or submits a full-page form, the current page will leave before further polling can render. For queued bulk actions, the progress handler should return the current queued job state during the redirected page render; the browser trigger only starts polling for the current page before the form submit leaves.

By default the progress bar uses the same desktop width as chart modules: half-width (col-12 col-xl-6). Call fullWidth() when the bar should span the full content width. color() accepts ColorsEnum values or CSS color strings and controls only the fill color; text uses the base Adminix theme color. On hover or keyboard focus, the track shows a percent tooltip that follows the animated fill position and updates with the same dynamic value as the header counter.

Architecture

ProgressBarModule follows the same module structure as other Adminix top modules:

the PHP DSL is implemented through ModuleMagicMethods;
Module::progressBar() and ModuleFactory create the module instance;
ModulesFactory resolves ProgressBarModuleDataProvider for page rendering;
ProgressBarStatusResolver calls the configured handler for the initial render and polling endpoint;
components/modules/progress_bar.blade.php renders the server-prepared state;
AdminixProgressBar handles triggers, polling, smooth fill animation, and animated numeric values in the browser.

CheckDataSource is not used because progress bars do not read from an Adminix datasource. The module receives state from an explicit ProgressBarHandlerInterface implementation instead.

Handler Contract

Handlers implement ProgressBarHandlerInterface and return ProgressBarResult. Handlers run during the initial page render and during later polling, so keep them idempotent and cheap: read current job state, do not start jobs or perform writes from the progress handler itself.

use AlexKudrya\Adminix\Modules\ProgressBar\ProgressBarHandlerInterface;
use AlexKudrya\Adminix\Modules\ProgressBar\ProgressBarRequest;
use AlexKudrya\Adminix\Modules\ProgressBar\ProgressBarResult;

final class ImportProgressHandler implements ProgressBarHandlerInterface
{
    public function handle(ProgressBarRequest $request): ProgressBarResult
    {
        $job = ImportJob::forTenant($request->params()[0] ?? null);

        if (! $job) {
            return ProgressBarResult::inactive();
        }

        return ProgressBarResult::fromValues(
            $job->processedRows(),
            $job->totalRows()
        );
    }
}

Result states:

ProgressBarResult::inactive() hides the bar and stops polling.
ProgressBarResult::active($percent) shows the bar and schedules the next poll.

The status only controls visibility and polling. The primary unit is percent, normalized into 0..100. Return ProgressBarResult::active(100) when a completed task should still be visible, or ProgressBarResult::inactive() when the backend wants to hide the bar and stop polling.

For absolute counters, call showValues() on the module and return either ProgressBarResult::active($percent)->values($current, $max) or ProgressBarResult::fromValues($current, $max). Adminix renders current / max centered under the track only when this option is enabled and the handler returns both values. The absolute row is display-only; inactive results still hide the whole progress module and stop polling.

Polling

pollIntervalSeconds() is configured in seconds and is clamped to a minimum of 1. This protects the backend from accidental high-frequency polling.

The progress endpoint receives signed page params through Adminix context, so handlers can use param:n-style page context without trusting browser-submitted values.

If the initial render returns active, Adminix shows the bar immediately and schedules the first browser poll after pollIntervalSeconds(). It does not send a duplicate immediate fetch just to initialize the bar.

Backend responses stop polling by returning inactive. Because Adminix does not use websockets, the backend cannot push an inactive bar into the running state; use progressTrigger() for user-started tasks. autoStart() remains available for rare screens that must immediately probe again from the browser after rendering, but most progress bars should rely on the server-rendered initial state plus triggers.

Doctor

php artisan adminix:doctor validates that a progress bar has a handler, that a class-string handler exists, and that it implements ProgressBarHandlerInterface.

Last modified: 21 June 2026