Filament Sticky Table Header Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require watheqalshowaiter/filament-sticky-table-header
   

2. Register the plugin in your PanelProvider (e.g., AdminPanelProvider):

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

3. Publish assets (if needed):

   php artisan filament:assets
   

First Use Case

Apply the plugin to any Filament table resource/page. The headers will automatically stick when scrolling down, improving usability for large datasets.

Implementation Patterns

Core Workflow

1. Global Application: Register the plugin in your PanelProvider to enable sticky headers across all tables in your Filament panel.

   StickyTableHeaderPlugin::make()
       ->shouldScrollToTopOnPageChanged() // Optional: Enable scroll-to-top behavior
   

2. Conditional Activation: Use the plugin selectively by wrapping it in a conditional check (e.g., based on user roles or table type):

   ->plugins([
       auth()->user()->isAdmin()
           ? StickyTableHeaderPlugin::make()
           : null,
   ])
   

3. Customizing Scroll Behavior: Configure scroll-to-top behavior for pagination changes:

   StickyTableHeaderPlugin::make()
       ->shouldScrollToTopOnPageChanged(enabled: true, behavior: "smooth")
   

   • behavior: "smooth" (default) or "instant".

4. Integration with Table Actions: The plugin positions sticky headers between edit/delete actions and filter dropdowns, ensuring UI consistency.

Advanced Patterns

• Dynamic Plugin Loading: Load the plugin dynamically in a resource’s getPages() or getWidgets() method:

  public function getPages(): array
  {
      return [
          Tables\UsersTable::class,
          // ...
      ] + (auth()->user()->isAdmin()
          ? [StickyTableHeaderPlugin::make()]
          : []);
  }
  

• Custom CSS Overrides: Extend the plugin’s default styles by publishing its assets and modifying the CSS:

  php artisan vendor:publish --tag=filament-sticky-table-header-assets
  

  Then override the styles in your app’s CSS file (e.g., resources/css/app.css).

• Testing: Test sticky behavior in your feature tests by simulating scroll events:

  $this->scrollPageToBottom();
  $this->assertSeeInViewport('Table Header Text');
  

Gotchas and Tips

Common Pitfalls

1. Asset Publishing: Forgetting to run php artisan filament:assets may result in broken sticky behavior. Run this command after installation or updates.

2. Conflicts with Dropdowns: In Filament v3, the plugin may conflict with dropdown menus. Ensure you’re using version 1.2.1+ for fixes:

   composer require watheqalshowaiter/filament-sticky-table-header:^1.2.1
   

3. Mobile Responsiveness: The plugin includes fixes for mobile screens (version 1.2.0+), but test on mobile devices to ensure headers remain usable.

4. Column Grouping Gaps: If using column grouping, gaps may appear. Update to 1.3.0+ for fixes:

   composer require watheqalshowaiter/filament-sticky-table-header:^1.3.0
   

Debugging Tips

• Inspect Elements: Use browser dev tools to verify the sticky header’s CSS classes (e.g., filament-sticky-table-header). Override these classes if needed.

• Check Plugin Registration: Ensure the plugin is registered after other plugins that might modify table behavior (e.g., sorting, filtering).

• Clear Cached Views: If changes aren’t reflected, clear Filament’s view cache:

  php artisan view:clear
  

Extension Points

1. Custom Styling: Override the plugin’s default styles by targeting its CSS classes:

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

2. Conditional Activation: Use Filament’s shouldRegisterNavigation or shouldRegisterSidebar patterns to conditionally enable the plugin:

   StickyTableHeaderPlugin::make()
       ->shouldRegisterNavigation(fn () => auth()->check())
   

3. Event Listeners: Extend the plugin’s behavior by listening to Filament’s events (e.g., TableRendered):

   use Filament\Tables\Events\TableRendered;
   
   TableRendered::listen(function (TableRendered $event) {
       if ($event->table->getName() === 'large-dataset-table') {
           // Custom logic for specific tables
       }
   });
   

4. Filament Version Compatibility: The plugin supports Filament 3.x, 4.x, and 5.x. Test thoroughly when upgrading Filament versions to avoid regressions.