Widgets Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require filament/widgets
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Filament\Widgets\WidgetServiceProvider"
   

2. First Widget Create a widget class (e.g., app/Filament/Widgets/StatsOverview.php):

   namespace App\Filament\Widgets;
   
   use Filament\Widgets\Widget;
   
   class StatsOverview extends Widget
   {
       protected static string $view = 'filament.widgets.stats-overview';
   }
   

   Register it in app/Providers/Filament/WidgetServiceProvider.php:

   public function register(): void
   {
       Widget::register(StatsOverview::class);
   }
   

3. First Usage Add the widget to a Livewire component (e.g., app/Filament/Pages/Dashboard.php):

   use App\Filament\Widgets\StatsOverview;
   
   public function widgets(): array
   {
       return [
           StatsOverview::class,
       ];
   }
   

4. View File Create a Blade view at resources/views/filament/widgets/stats-overview.blade.php:

   <x-filament::widget>
       <!-- Your widget content -->
   </x-filament::widget>
   

Implementation Patterns

Widget Organization

• Grouping Widgets Use Widget::group() to categorize widgets (e.g., Analytics, System).

  Widget::group('Analytics', [
      StatsOverview::class,
      TrafficSources::class,
  ]);
  

• Dynamic Widgets Fetch widgets dynamically from a database or API:

  public function widgets(): array
  {
      return Widget::query()
          ->where('user_id', auth()->id())
          ->get()
          ->map(fn ($widget) => $widget->class);
  }
  

Integration with Livewire

• Layout Customization Override default widget layout in resources/views/vendor/filament/widgets/layouts/default.blade.php.

• Conditional Rendering Use shouldRender() to control visibility:

  public function shouldRender(): bool
  {
      return auth()->user()->can('view_dashboard');
  }
  

• Real-Time Updates Extend Widget and use Livewire’s updates property for reactivity:

  public ?string $updates = ['data'];
  

Styling and Theming

• Tailwind Classes Leverage Filament’s built-in Tailwind classes (e.g., p-4, bg-white).
• Custom CSS Add widget-specific CSS in resources/css/filament/widgets.css.

Reusable Widget Components

• Shared Logic Extract common logic into traits or base classes:

  use Filament\Widgets\Concerns\InteractsWithData;
  
  class BaseWidget extends Widget
  {
      use InteractsWithData;
  }
  

Gotchas and Tips

Common Pitfalls

• Widget Registration Order Ensure widgets are registered before they’re used (e.g., in boot() of WidgetServiceProvider).

• View Path Conflicts If using custom view paths, explicitly set $view in the widget class to avoid autoloading issues.

• Livewire Hooks Widgets don’t automatically inherit Livewire hooks (e.g., mount, hydrate). Override them explicitly if needed.

Debugging

• Missing Widgets Check:

  • Widget is registered in WidgetServiceProvider.
  • View file exists at the correct path.
  • No typos in class names or view references.

• Styling Issues Use browser dev tools to inspect Filament’s default styles. Override with !important if necessary (sparingly).

Performance Tips

• Lazy-Loading For heavy widgets, use shouldRender() to defer loading until needed.
• Caching Cache widget data in getData() if the source is static or rarely changes:

  public function getData(): array
  {
      return Cache::remember('widget-data', now()->addHours(1), function () {
          return $this->fetchDataFromDatabase();
      });
  }
  

Extension Points

• Custom Widget Types Extend Widget to create specialized widgets (e.g., ChartWidget, FormWidget).
• Widget Events Dispatch events in widgets for global side effects:

  event(new WidgetRendered($this));
  

• API Integration Use Http facade or Guzzle to fetch remote data in getData():

  public function getData(): array
  {
      return Http::get('https://api.example.com/stats')->json();
  }
  

Config Quirks

• Default Widget Layout Override filament.widgets.layout in config/filament.php:

  'widgets' => [
      'layout' => 'filament.widgets.layouts.custom',
  ],
  

• Widget Icons Use Filament’s icon helpers (e.g., Icon::make('heroicon-o-chart-bar')) in views.

Testing

• Unit Tests Mock widget data in tests:

  $widget = new StatsOverview();
  $widget->setData(['value' => 100]);
  $this->assertEquals(100, $widget->data['value']);
  

• Livewire Tests Test widget rendering in Livewire components:

  $this->livewire(Dashboard::class)
       ->assertSee('Widget Content');