Progress Bar

• Table of contents
• Features
• Requirements
• Installation
• Quick start
  • Table column
  • Infolist entry
• API reference
  • Value
  • Display
  • Color
  • Icon
  • Accessibility
• Enums
• Real-world example
• Theming & customisation
  • Custom colors
• Translations
• Publishing resources
• Testing
• Troubleshooting
• Security
• Contributing
• Credits
• License

A feature-rich Filament v5 table column & infolist entry that renders progress as a horizontal bar. Built for dashboards, task progress, capacity gauges, skill levels, and any numeric value that fits on a 0–100% (or custom min–max) scale.

#Table of contents

• Features
• Requirements
• Installation
• Quick start
• API reference
  • Value
  • Display
  • Color
  • Icon
  • Accessibility
• Enums
• Real-world example
• Theming & customisation
• Translations
• Publishing resources
• Testing
• Troubleshooting
• Security
• Contributing
• Credits
• License

#Features

• Table column — drop into any Filament table as a percentage/gauge column
• Infolist entry — read-only progress visualisation for detail pages
• 4 sizes — Tiny, Small, Medium, Large
• 3 shapes — Rounded, Pill, Square
• 6 colors — primary / success / warning / danger / info / gray, plus custom panel colors
• Threshold-driven colors — ->thresholds([90 => 'success', 50 => 'warning', 0 => 'danger'])
• Warn above — ->warnAbove(100) auto-flags over-budget values
• Stripes + animation — striped or scrolling diagonal pattern overlay
• Indeterminate — looping animation when the progress is unknown
• Gradient fill — smooth left→right colour transition
• Label anywhere — inside, outside, or hidden; custom formatter with full control
• Icons — start/end icon adjacent to the label
• ARIA-compliant — always emits role="progressbar", aria-valuenow/min/max, aria-label
• Type-safe enums — Size::Large, Shape::Pill, LabelPosition::Outside, IconPosition::End; strings still work
• Self-contained CSS — Tailwind-compiled, no dependency on Filament's button/badge classes
• Translations — en and ar shipped

#Requirements

• PHP 8.2+
• Laravel 11+
• Filament v5+
• Tailwind CSS (via a custom Filament theme if you use Panels)

#Installation

composer require aureuserp/progress-bar

Service provider is auto-discovered. CSS is registered via FilamentAsset and published automatically during artisan filament:assets.

#Quick start

#Table column

use Webkul\ProgressBar\Tables\Columns\ProgressBar;

ProgressBar::make('progress')
    ->label('Completion')
    ->color(fn ($record) => $record->progress >= 100 ? 'success' : 'primary');

#Infolist entry

use Webkul\ProgressBar\Infolists\Components\ProgressBar;

ProgressBar::make('level')
    ->label('Skill level')
    ->getStateUsing(fn ($record) => $record->level);

Both components extend Filament base classes (Column and Entry), so every standard method (->label(), ->sortable(), ->toggleable(), ->visible()) still works.

#API reference

#Value

->max(int | float | Closure $max = 100)           // upper bound (default 100)
->min(int | float | Closure $min = 0)             // lower bound (default 0)
->value(int | float | Closure $value)             // explicit state override
->precision(int $decimals = 2)                    // decimals for non-100% display
->formatLabel(Closure $fn)                        // full control: (value, percentage, min, max) → string

#Display

use Webkul\ProgressBar\Enums\{Size, Shape, LabelPosition};

->size(Size::Large)                               // or 'lg'   — Tiny | Small | Medium | Large
->shape(Shape::Pill)                              // or 'pill' — Rounded | Pill | Square
->labelPosition(LabelPosition::Outside)            // or 'outside' — Inside | Outside | None
->showLabel(bool | Closure $condition = true)      // shortcut: false → LabelPosition::None
->striped(bool | Closure = true)                   // diagonal stripes
->animated(bool | Closure = true)                  // scrolling stripes (implies striped)
->indeterminate(bool | Closure = true)             // sliding animation (value ignored)
->gradient(bool | Closure = true)                  // left→right colour gradient

#Color

->color(string | Closure $color)                   // primary / success / warning / danger / info / gray / custom
->trackColor(string | Closure $color = 'gray')     // unfilled-track color
->thresholds(array | Closure $map)                 // [90=>'success', 75=>'info', 50=>'warning', 0=>'danger']
->warnAbove(int | float $threshold,
            string $color = 'danger')              // over-threshold paints with $color

Resolution order: warnAbove → thresholds → color() → fallback primary.

#Icon

use Webkul\ProgressBar\Enums\IconPosition;

->icon(string | Closure $heroicon)                 // 'heroicon-m-check-circle' etc.
->iconPosition(IconPosition::End)                   // or 'end' — Start | End

#Accessibility

Every render emits:

<div class="pb-track" role="progressbar"
     aria-valuenow="{percentage}"
     aria-valuemin="{min}"
     aria-valuemax="{max}"
     aria-label="{formatted label}">
    <div class="pb-fill" style="width: {percentage}%"></div>
</div>

For indeterminate bars, aria-valuenow is omitted (per the WAI-ARIA spec).

#Enums

Each exposes a default() static. Setters accept Enum | string | Closure; getters return the string value so Blade data-pb-* attributes and the CSS keep working unchanged.

use Webkul\ProgressBar\Enums\{Size, Shape, LabelPosition, IconPosition};

ProgressBar::make('progress')
    ->size(Size::Large)
    ->shape(Shape::Pill)
    ->labelPosition(LabelPosition::Outside)
    ->icon('heroicon-m-check-circle')
    ->iconPosition(IconPosition::End);

#Real-world example

Adapted from a skill-level table (the pattern that originally motivated the extraction):

use Webkul\ProgressBar\Enums\Shape;
use Webkul\ProgressBar\Enums\Size;
use Webkul\ProgressBar\Tables\Columns\ProgressBar;

ProgressBar::make('level')
    ->label('Proficiency')
    ->getStateUsing(fn ($record) => $record->level)
    ->size(Size::Small)
    ->shape(Shape::Pill)
    ->striped()
    ->thresholds([
        80 => 'success',
        50 => 'warning',
        20 => 'info',
        0  => 'danger',
    ])
    ->formatLabel(fn (float $percentage, float $value) => sprintf('%d / 100', $value))
    ->sortable()
    ->toggleable();

Task progress in a project dashboard:

ProgressBar::make('progress')
    ->label('Completion')
    ->warnAbove(100, 'danger')              // over-budget → red
    ->color(fn ($record) => $record->progress >= 100 ? 'success' : 'primary')
    ->animated()
    ->size(Size::Medium);

#Theming & customisation

The plugin ships a Tailwind-compiled CSS bundle keyed on stable data attributes you can target in your own theme:

• .pb-wrapper — outer wrapper (flex column, used for outside-label layout)
• .pb-track — the track
• .pb-fill — the filled portion
• .pb-label / .pb-label-outside — label text
• .pb-icon — icon inside the label

Data attributes on .pb-track:

• data-pb-size="xs|sm|md|lg" — height
• data-pb-shape="rounded|pill|square" — corner radius
• data-pb-color="primary|success|warning|danger|info|gray|…" — drives --pb-color-500/600 CSS variables
• data-pb-indeterminate="true|false" — triggers the slide animation

Data attributes on .pb-fill:

• data-pb-striped="true" — adds diagonal stripes
• data-pb-animated="true" — animates the stripes
• data-pb-gradient="true" — left→right colour gradient
• data-pb-full="true" — set when progress is 100% (used to switch label colour to white)

#Custom colors

Register a panel color and reference it in the progress bar:

// AdminPanelProvider
->colors(['magenta' => '#b72d81'])

// Usage
->color('magenta')

#Translations

Ships with en and ar under the progress-bar:: namespace for aria labels and enum display names. Publish to override:

php artisan vendor:publish --tag="progress-bar-translations"

#Publishing resources

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

#Testing

vendor/bin/pest plugins/aureuserp/progress-bar/tests/Feature

The plugin ships a full Pest suite covering:

Fixtures live at tests/Feature/Fixtures/.

#Troubleshooting

#Security

Email support@aureuserp.com for security-related reports instead of opening a public issue.

#Contributing

PRs welcome. Before submitting:

vendor/bin/pest plugins/aureuserp/progress-bar/tests/Feature
vendor/bin/pint plugins/aureuserp/progress-bar

When adding a new option:

1. Define a BackedEnum under src/Enums/ if the option is one of a fixed set.
2. Accept both the enum and the raw string in the setter signature.
3. Add coverage under tests/Feature/Unit/.
4. Document the option in the API reference and Enums sections.

#Credits

• AureusERP — plugin author
• Filament team — the excellent admin framework
• filamentphp/plugin-skeleton — structural template

#License

MIT. See LICENSE.md.