Filament Sticky Table Header Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require watheqalshowaiter/filament-sticky-table-header
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="FilamentStickyTableHeader\FilamentStickyTableHeaderServiceProvider"
   

2. Register the Plugin Add to app/Providers/Filament/AppServiceProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \FilamentStickyTableHeader\FilamentStickyTableHeaderPlugin::make(),
           ]);
   }
   

3. First Use Case Apply sticky headers to a table in a Filament resource/page:

   use FilamentStickyTableHeader\Concerns\HasStickyTableHeaders;
   
   public static function table(Table $table): Table
   {
       return $table
           ->columns([
               // columns...
           ])
           ->plugins([
               HasStickyTableHeaders::make(),
           ]);
   }
   

Implementation Patterns

Common Workflows

1. Global vs. Per-Table Activation

   • Global: Enable for all tables via config (config/filament-sticky-table-header.php):

     'default' => true,
     

   • Per-Table: Opt-in via plugin:

     ->plugins([HasStickyTableHeaders::make()])
     

2. Conditional Sticky Headers Use middleware or logic to toggle sticky headers dynamically:

   ->plugins([
       HasStickyTableHeaders::make()->when(fn (User $user) => $user->prefers_sticky_headers()),
   ])
   

3. Custom Styling Override default styles via CSS (target .filament-sticky-table-header):

   .filament-sticky-table-header {
       background: #f8f9fa;
       z-index: 10;
   }
   

4. Integration with Filament Actions Ensure sticky headers work seamlessly with bulk actions or filters:

   ->actions([
       Tables\Actions\DeleteBulkAction::make(),
   ])
   ->plugins([HasStickyTableHeaders::make()])
   

Pro Tips

• Performance: Disable for small tables (<10 rows) via config:

  'min_rows_for_sticky' => 10,
  

• Responsive Design: Use responsive modifier for mobile:

  HasStickyTableHeaders::make()->responsive()
  

• Nested Tables: Works with nested tables (Filament 3+):

  ->columns([
      Tables\Columns\TextColumn::make('nested_data')
          ->table(fn (Model $record) => $record->relatedModels)
          ->plugins([HasStickyTableHeaders::make()]),
  ])
  

Gotchas and Tips

Pitfalls

1. Z-Index Conflicts

   • Issue: Sticky headers may hide Filament modals/dialogs.
   • Fix: Increase z-index in custom CSS or adjust Filament’s modal z-index (e.g., !important in resources/css/filament.css).

2. Scrollbar Jumps

   • Issue: Content shifts when headers stick on scroll.
   • Fix: Ensure overflow-y: auto is set on the table container:

     .filament-table-container {
         overflow-y: auto;
         height: calc(100vh - 120px); /* Adjust as needed */
     }
     

3. Filament 3 vs. 4

   • Filament 3: Use filament/sticky-table-header namespace.
   • Filament 4: Use FilamentStickyTableHeader namespace (check composer.json for version compatibility).

4. Dynamic Column Changes

   • Issue: Headers may not update if columns are added/removed dynamically (e.g., via JavaScript).
   • Fix: Reinitialize the plugin or use useStickyTableHeaders() hook:

     ->plugins([
         HasStickyTableHeaders::make()->hook('useStickyTableHeaders', fn () => {
             // Re-render logic if needed
         }),
     ])
     

Debugging

• Console Errors: Check for Uncaught TypeError if the plugin fails to load. Ensure:
  • Filament is fully bootstrapped.
  • No JavaScript errors block the plugin’s initialization.
• Browser DevTools: Inspect .filament-sticky-table-header to verify styles are applied.

Extension Points

1. Custom Header Content Override the header template via Blade:

   HasStickyTableHeaders::make()->view('filament-sticky-table-header::custom-header');
   

   Create resources/views/filament-sticky-table-header/custom-header.blade.php:

   <div class="sticky-header">
       @include('filament::table.header')
       <!-- Add custom elements here -->
   </div>
   

2. Server-Side Processing For large datasets, ensure the plugin works with livewire:ignore:

   ->plugins([
       HasStickyTableHeaders::make()->ignoreLivewire(),
   ])
   

3. Localization Translate labels (e.g., "Sticky Header") via Filament’s localization system:

   HasStickyTableHeaders::make()->label(__('filament-sticky-table-header::labels.sticky'));