Filament Sticky Header Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require awcodes/filament-sticky-header
   

2. Ensure a custom theme is configured (required for Filament Panels). Follow Filament's theme docs.
3. Import the plugin's CSS in your theme file:

   @import '../../../../vendor/awcodes/filament-sticky-header/resources/css/plugin.css';
   

4. Register the plugin in your PanelProvider:

   use Awcodes\StickyHeader\StickyHeaderPlugin;
   
   public function panel(Panel $panel): Panel {
       return $panel
           ->plugins([
               StickyHeaderPlugin::make(),
           ]);
   }
   

First Use Case

Enable sticky headers for all pages in your Filament panel. The plugin automatically applies to resource pages (e.g., PostsTable, PostsCreateEditPage) and custom pages.

Implementation Patterns

Core Workflow

1. Default Behavior:

   • Sticky headers activate on scroll for all pages except list pages (tables).
   • Useful for forms, details views, and custom pages where context matters.

2. Conditional Activation:

   • Floating Theme: Use floating() for a detached, floating header:

     StickyHeaderPlugin::make()->floating()
     

   • Colored Header: Apply primary background color with colored():

     StickyHeaderPlugin::make()->floating()->colored()
     

   • Runtime Conditions: Pass closures for dynamic control:

     StickyHeaderPlugin::make()
         ->floating(fn () => auth()->user()->prefers_floating_header)
     

3. Exclusions:

   • List Pages: Disable for tables with stickOnListPages(false):

     StickyHeaderPlugin::make()->stickOnListPages(false)
     

   • Custom Pages: Exclude specific pages by class:

     StickyHeaderPlugin::make()->disabledOn([
         App\Filament\Pages\MyCustomPage::class,
     ])
     

     Or dynamically:

     StickyHeaderPlugin::make()->disabledOn(fn () => [
         auth()->user()->is_admin ? AdminDashboard::class : [],
     ])
     

4. Integration with Filament Features:

   • Notifications: The plugin handles overlay conflicts (e.g., toast notifications) via CSS z-index adjustments.
   • Navigation: Automatically reinitializes on route changes (wire:navigated events).

Advanced Patterns

• Theme Customization: Override the plugin’s CSS in your theme file to match your design system. Target classes like:

  .filament-sticky-header {
      /* Custom styles */
  }
  

• JavaScript Hooks: Extend functionality by listening to the plugin’s events (e.g., sticky-header:stick, sticky-header:unstick). Use Alpine.js or Livewire hooks:

  document.addEventListener('sticky-header:stick', () => {
      console.log('Header stuck!');
  });
  

Gotchas and Tips

Pitfalls

1. Missing Custom Theme:

   • Error: Sticky headers may not render or appear broken.
   • Fix: Ensure you’ve followed Filament’s theme setup before adding the plugin.

2. CSS Conflicts:

   • Issue: Overlapping with other sticky elements (e.g., Filament’s top bar).
   • Fix: Inspect the generated HTML and adjust z-index in your theme:

     .filament-sticky-header {
         z-index: 50; /* Higher than Filament's top bar */
     }
     

3. JavaScript Scope:

   • Issue: Plugin JS may interfere with other scripts if not scoped.
   • Fix: The package v4+ scopes JS to the panel context by default. No action needed unless debugging.

4. Performance:

   • Issue: Excessive re-renders on scroll (rare but possible with complex pages).
   • Fix: Use the floating() theme for smoother transitions, as it decouples from scroll events.

Debugging Tips

• Check Console: Look for errors like Uncaught TypeError if the plugin fails to load. Ensure the CSS import path is correct.
• Inspect Elements: Verify the .filament-sticky-header class is applied to the correct element.
• Disable Plugins: Temporarily remove the plugin to isolate issues (e.g., conflicts with other Filament plugins).

Extension Points

1. Custom Styling:
   • Override the default transition or shadow effects by targeting:

     .filament-sticky-header.transitioning {
         transition: transform 0.3s ease;
     }
     

2. Dynamic Logic:
   • Extend the disabledOn closure to exclude pages based on user roles, permissions, or other runtime conditions:

     ->disabledOn(fn () => [
         auth()->user()->cannot('view-dashboard') ? Dashboard::class : [],
     ])
     

3. Event Listening:
   • Listen for scroll events or plugin state changes via Alpine.js:

     window.addEventListener('alpine:init', () => {
         Alpine.data('stickyHeader', () => ({
             init() {
                 this.$watch('scroll', (value) => {
                     console.log('Scroll position:', value);
                 });
             }
         }));
     });
     

Pro Tips

• Combine with Other Plugins: Use alongside filament-notifications or filament-spinners for a polished UX. The plugin handles z-index conflicts out of the box.
• A/B Testing: Use the floating() and colored() closures to test different header styles with users:

  ->floating(fn () => request()->query('theme') === 'floating')
  

• Performance Monitoring: For large panels, monitor scroll performance with Chrome DevTools’ Performance tab. The floating theme is lighter on scroll events.