Filament Progress Bar Column Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tapp/filament-progress-bar-column
   

2. Publish Config (if needed):

   php artisan vendor:publish --provider="Tapp\FilamentProgressBarColumn\FilamentProgressBarColumnServiceProvider"
   

3. Register the Column: Add to your Filament table definition:

   use Tapp\FilamentProgressBarColumn\Columns\ProgressBarColumn;
   
   ProgressBarColumn::make('progress_field')
       ->label('Progress')
       ->value(fn ($record) => $record->progress_value)
       ->max(100) // Optional: Set max value
       ->statuses([
           'danger' => ['label' => 'Critical', 'min' => 0, 'max' => 30],
           'warning' => ['label' => 'Low', 'min' => 30, 'max' => 70],
           'success' => ['label' => 'Good', 'min' => 70, 'max' => 100],
       ]);
   

First Use Case

Replace a numeric column with a visual progress bar for task completion:

use App\Models\Task;

TaskResource::class
    ->table([
        // ... other columns
        ProgressBarColumn::make('completion_percentage')
            ->label('Progress')
            ->value(fn ($record) => $record->completion_percentage)
            ->statuses([
                'danger' => ['label' => 'Blocked', 'min' => 0, 'max' => 50],
                'warning' => ['label' => 'At Risk', 'min' => 50, 'max' => 90],
                'success' => ['label' => 'Complete', 'min' => 90, 'max' => 100],
            ]),
    ]);

Implementation Patterns

Core Workflow

1. Define Status Thresholds:

   ProgressBarColumn::make('disk_usage')
       ->statuses([
           'danger' => ['label' => 'Full', 'min' => 90, 'max' => 100],
           'warning' => ['label' => 'Low', 'min' => 70, 'max' => 90],
           'success' => ['label' => 'OK', 'min' => 0, 'max' => 70],
       ]);
   

2. Dynamic Value Calculation:

   ProgressBarColumn::make('inventory_level')
       ->value(fn ($record) => ($record->stock / $record->max_stock) * 100)
       ->max(100);
   

3. Reusable Column Class: Create a base column for consistent styling:

   namespace App\Filament\Columns;
   
   use Tapp\FilamentProgressBarColumn\Columns\ProgressBarColumn;
   
   class StandardProgressColumn extends ProgressBarColumn
   {
       protected static ?string $defaultStatuses = [
           'danger' => ['label' => 'Critical', 'min' => 0, 'max' => 30],
           'warning' => ['label' => 'Warning', 'min' => 30, 'max' => 70],
           'success' => ['label' => 'OK', 'min' => 70, 'max' => 100],
       ];
   }
   

Integration Tips

• With Filament Actions: Combine with actions for quick responses:

  ProgressBarColumn::make('priority')
      ->value(fn ($record) => $record->priority)
      ->statuses([...])
      ->extraAttributes(['class' => 'cursor-pointer'])
      ->action(function ($record) {
          return Action::make('Escalate')
              ->action(fn ($record) => $record->escalate());
      });
  

• Conditional Rendering:

  ProgressBarColumn::make('health')
      ->visible(fn ($record) => $record->is_monitored)
      ->value(fn ($record) => $record->health_score);
  

• Custom Styling: Override Tailwind classes in your tailwind.config.js:

  content: [
      './vendor/tapp/filament-progress-bar-column/resources/views/**/*.blade.php',
  ],
  safelist: [
      'bg-red-500', 'bg-yellow-500', 'bg-green-500',
      'h-2', 'rounded-full', 'transition-colors'
  ],
  

Gotchas and Tips

Common Pitfalls

1. Threshold Gaps:

   • Ensure statuses ranges cover the full max value (e.g., min of next status = max of previous + 1).
   • Fix: Add a default success status if gaps exist:

     ->statuses([
         'danger' => ['min' => 0, 'max' => 30],
         'warning' => ['min' => 30, 'max' => 70],
         // Auto-adds 'success' for 70-100
     ]);
     

2. Floating-Point Precision:

   • Values like 99.999 may not trigger the correct status.
   • Fix: Round values or adjust thresholds:

     ->value(fn ($record) => round($record->progress * 100) / 100)
     

3. Tailwind Class Conflicts:

   • Custom styles may override the package’s Tailwind classes.
   • Fix: Use !important sparingly or extend the package’s CSS:

     /* resources/css/filament.css */
     .filament-progress-bar-column .progress {
         @apply h-2 rounded-full transition-colors !important;
     }
     

Debugging Tips

• Inspect Rendered HTML: Use browser dev tools to verify ARIA attributes (role="progressbar", aria-valuenow, etc.) are present.

• Log Status Calculation: Temporarily add a ->value() closure to debug:

  ->value(fn ($record) => (clone $record)->tap(fn ($r) => logger()->debug('Progress:', ['value' => $r->progress, 'status' => $this->getStatus($r->progress)]))->progress)
  

Extension Points

1. Custom Status Logic: Override getStatus() in a custom column class:

   public static function getStatus($value, $max = null): string
   {
       if ($value > 80) return 'critical';
       return parent::getStatus($value, $max);
   }
   

2. Dynamic Statuses: Fetch thresholds from a config or database:

   ->statuses(config('app.progress_thresholds'))
   // or
   ->statuses(fn ($record) => $record->getThresholds())
   

3. Accessibility: Add custom ARIA labels:

   ->extraAttributes(['aria-label' => 'Task completion progress'])
   

4. Server-Side Processing: For large datasets, ensure value() closures are optimized:

   // Avoid N+1 queries
   ->value(fn ($record) => $record->progress_cache ?? $record->calculateProgress())