Progress Laravel Package

Getting Started

Install and pin. The package is MIT-licensed, has zero dependents, and sits on a 3.x line where the changelog is almost entirely Dependabot bumps plus a fix in blade file. Use an exact constraint until you've read the source:

composer require lara-zeus/progress:3.0.1

Then run the install command only if the service provider publishes anything (views/config/assets). Check with php artisan list | grep -i progress rather than assuming — the description doesn't advertise migrations, and there is no reason to expect any for a presentational component.

Read the source before writing a call site. This takes under an hour and is the highest-value step. Three questions:

1. Is it purely presentational (a value/max pair rendered into HTML), or does it compute/persist anything? Assume presentational until proven otherwise; that determines whether this saves an hour or is just a styled <progress> tag.
2. What is the exact component tag and prop signature? The advertised surface is value, max, color/size, label. Confirm names and types in the Blade file — don't guess at <x-zeus-progress> in a template and debug a silent empty render later.
3. Filament column or plain Blade, or both? The description claims "works as a Filament column." Find the FQCN in the package's src/ (likely LaraZeus\Progress\Tables\Columns\...) and check whether a Plugin class with register(Panel $panel) exists or whether registration is purely Blade-based.

Tailwind before you judge the visuals. If the package ships its own views, add them to content in tailwind.config.js and rebuild. An unstyled bar is the #1 false alarm with packages in this size class:

content: [
    './resources/**/*.blade.php',
    './vendor/lara-zeus/progress/resources/views/**/*.blade.php',
],

First use case: an admin dashboard, not a customer surface. Onboarding completion percentage for a user, storage quota usage, or a project's task-completion bar. It exercises value/max/label/color, it's low-stakes if the render is wrong, and it requires no persistence work — you're feeding it integers you already have.

Also confirm Laravel/Filament compatibility explicitly. Nothing in the docs states supported majors; composer show lara-zeus/progress and the composer.json require block are your source of truth before you plan a Filament upgrade around it.

Implementation Patterns

Wrap it behind your own component on day one. With one maintainer, one star, and zero dependents, the package should be a single implementation detail behind a stable contract you own:

{{-- resources/views/components/progress-bar.blade.php --}}
@props(['value', 'max' => 100, 'label' => null, 'variant' => 'default'])

@php
    $max    = max(1, (int) $max);              // never divide by zero
    $value  = min(max(0, (int) $value), $max); // clamp out-of-range input
    $pct    = (int) round($value / $max * 100);
@endphp

<x-zeus-progress
    :value="$value"
    :max="$max"
    :label="$label ?? $pct . '%'"
    {{ $attributes->class(['min-h-2']) }}
/>

Every call site binds to <x-progress-bar>. Swapping to a hand-rolled 60-line Blade component later becomes a one-file change — that's the entire ROI here.

Compute percentages in a presenter or accessor, not in templates. Progress is rarely a raw column, and you want the arithmetic testable:

final class OnboardingProgress
{
    public function __construct(private User $user) {}

    public function earned(): int
    {
        return collect([
            'avatar'  => filled($this->user->avatar_path),
            'bio'     => filled($this->user->bio),
            'email'   => $this->user->email_verified_at !== null,
            'team'    => $this->user->teams()->exists(),
        ])->filter()->count();
    }

    public function total(): int { return 4; }
}

<x-progress-bar
    :value="(new OnboardingProgress($user))->earned()"
    :max="(new OnboardingProgress($user))->total()"
    label="{{ __('Profile setup') }}"
/>

Normalize weighted milestones to a common denominator. Steps are almost never equally weighted. Convert to points, hand the package two integers:

$points = ['account' => 10, 'profile' => 25, 'first_project' => 40, 'team' => 25];

$earned = collect($points)
    ->filter(fn ($_, $key) => $milestones[$key] ?? false)
    ->sum();

// <x-progress-bar :value="$earned" :max="array_sum($points)" />

Filament table column. Where the package shines day-to-day is inline table display — a quota or completion bar per row is far more scannable than a percentage number:

// Verify the FQCN in the package's src/Tables/Columns directory first.
use LaraZeus\Progress\Tables\Columns\ProgressColumn;

ProgressColumn::make('completed_tasks')
    ->label('Progress')
    ->maxValue(fn ($record) => $record->total_tasks ?: 1),  // guard against 0

If the column class doesn't accept a dynamic max, compute the percentage in a model accessor ($record->progress_pct) and feed a 0–100 value instead. That fallback keeps the work in your code and out of the vendor's prop surface.

Live progress: you own the pipeline. The package supplies pixels only. For a queued import, write status from the job to a table or cache, then poll from a Livewire component:

class ImportProgress extends Component
{
    public string $importId;

    public function render()
    {
        $status = ImportStatus::findOrFail($this->importId);

        return view('livewire.import-progress', [
            'processed' => $status->processed,
            'total'     => max(1, $status->total),
            'failedAt'  => $status->failed_at,
        ]);
    }
}

<div wire:poll.2s>
    <x-progress-bar :value="$processed" :max="$total" />

    @if ($failedAt)
        <p class="text-sm text-red-600">
            {{ __('Import failed at :n of :t.', ['n' => $processed, 't' => $total]) }}
        </p>
    @endif
</div>

Always render the terminal failure branch. A bar that silently freezes at 60% is worse than no bar.

Standardize variants centrally. If the package supports color/size props, map them in the wrapper (variant="danger" past 90% quota) rather than passing raw colors at call sites — otherwise you get five shades of warning yellow across the admin panel.

Dashboard widget composition. A Filament stats widget that stacks three or four bars (storage, onboarding, open tickets vs. SLA) is the cheapest high-perceived-value pilot, and it's where adoption cost is lowest because styling and upgrade cadence are shared with the lara-zeus/Filament ecosystem.

Gotchas and Tips

Unstyled output is a build problem, not a bug. Vendor view path missing from Tailwind content, assets not published, or dynamically constructed class names that JIT can't see (needs a safelist entry). Check these three before opening an issue.

Divide-by-zero and out-of-range values. max = 0 happens constantly — a new user with no steps, an empty collection, a quota that hasn't loaded. Naive math throws or renders a full bar. Clamp once in the wrapper; never trust call sites to sanitize.

Verify accessibility yourself. A determinate bar needs role="progressbar", aria-valuenow, aria-valuemin, aria-valuemax, and a text alternative. A one-star package is unlikely to have this hardened. Inspect the rendered HTML once; if attributes are missing, add them via {{ $attributes }} pass-through in your wrapper — another concrete reason for the wrapper to exist.

Pin the Filament major and treat upgrades as a review item. Filament plugins routinely lag panel upgrades and fail silently (blank cell, default styling) rather than throwing. Add lara-zeus/progress to the same checklist as the Filament bump and visually diff the pilot surface afterwards.

Localize at the wrapper, not inside the package. Assume no shipped translations. Pass label="{{ __('Profile setup') }}" from the call site so hardcoded English never reaches the UI.

Fix the height to avoid layout shift. If the package animates width or you poll a value, tables and cards will jump as numbers change. Pin min-h-* (or an explicit height) in the wrapper's class list.

Scope creep is the real risk. "Add a progress bar" is an afternoon; "add job progress" is a sprint — job-status persistence, broadcast or polling endpoints, retry/backoff, failure and cancellation states, and auditability are all yours. Estimate them separately, and never let the package's existence imply it handles tracking.

Test through your wrapper, not the vendor's output. Assert percentages at your abstraction layer so tests survive a swap:

it('renders onboarding progress', function () {
    $user = User::factory()->create(['bio' => 'hello', 'email_verified_at' => now()]);

    $this->actingAs($user)->get('/dashboard')->assertSee('50%');
});

Plan to own the fork. One maintainer, no production dependents. Assume that within two quarters a needed fix means patching a Blade file yourself. Keep its views and any classes out of your domain layer, don't extend its classes, and don't rely on internals that aren't in the published README. If you need a segmented bar, step dots, or a circular gauge, build it against your own prop contract and drop the dependency for that surface — call sites won't change.