Filament Sticky Columns Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require zeeshantariq/filament-sticky-columns
   

2. Integrate assets (choose one):

   • Vite (recommended): Add CSS to resources/css/filament/admin/theme.css:

     @import "../../../../vendor/zeeshantariq/filament-sticky-columns/resources/css/filament-sticky-columns.css";
     

     Import JS in your panel’s JS bundle:

     import '../../../../vendor/zeeshantariq/filament-sticky-columns/resources/js/filament-sticky-columns.js'
     

     Run:

     npm run dev
     

   • Filament assets pipeline: Publish assets:

     php artisan filament:assets
     

3. First use case: Replace a TextColumn with StickyColumn in your table definition:

   use ZeeshanTariq\FilamentStickyColumns\Columns\StickyColumn;
   
   StickyColumn::make('id')->sortable(),
   

Implementation Patterns

Core Workflows

1. Drop-in replacement: Use StickyColumn for left-sticky columns (default):

   StickyColumn::make('name')->searchable(),
   

2. Macro-based stickiness: Apply stickiness to any column via macros:

   TextColumn::make('status')->stickyRight()->badge(),
   

3. Dynamic table updates: Refresh sticky columns after AJAX/table changes:

   // In your JS logic (e.g., after Livewire update)
   window.FilamentStickyColumns.refresh();
   

Integration Tips

• Conditional stickiness: Use the condition parameter to enable/disable stickiness dynamically:

  TextColumn::make('priority')->sticky(condition: $this->isAdminView),
  

• Z-index management: Override default z_index in config or per-column:

  StickyColumn::make('id')->sticky(zIndex: 20),
  

• Right-aligned sticky columns: Combine with badge() or icon() for visual clarity:

  StickyColumn::make('status')->right()->badge()->color(fn ($record) => $record->status === 'active' ? 'success' : 'danger'),
  

• Complex layouts: Use manual offsets for columns adjacent to fixed-width elements (e.g., checkboxes):

  StickyColumn::make('name')->sticky(offset: 60), // After 60px checkbox column
  

Advanced Patterns

• Theme-aware stickiness: Leverage Filament’s dark mode via background: 'auto' in config. Override per-column if needed:

  StickyColumn::make('id')->sticky(background: 'bg-gray-100 dark:bg-gray-800'),
  

• Multi-level stickiness: Combine with Filament’s extraAttributes() for nested sticky elements:

  StickyColumn::make('details')->sticky()->extraAttributes(['class' => 'group-hover:bg-gray-50']),
  

• Livewire event hooks: Reinitialize sticky columns after Livewire updates:

  document.addEventListener('livewire:update', () => {
      window.FilamentStickyColumns.refresh();
  });
  

Gotchas and Tips

Pitfalls

1. Asset pipeline issues:

   • Symptom: Sticky columns not applying after composer update.
   • Fix: Run php artisan filament:assets (or filament:upgrade if in Composer scripts). For Vite, rebuild assets (npm run dev).

2. Filament v4/v5 cell targeting:

   • Symptom: Sticky classes appear on inner <div> instead of <th>/<td>.
   • Fix: Use extraHeaderAttributes()/extraCellAttributes() to ensure data-sticky is on the cell:

     StickyColumn::make('id')->extraHeaderAttributes(['data-sticky' => 'left']),
     

3. Offset miscalculations:

   • Symptom: Sticky columns overlap or misalign.
   • Fix: Use manual offsets for dynamic columns (e.g., with checkboxes):

     StickyColumn::make('name')->sticky(offset: 50), // Adjust based on checkbox width
     

4. Dark mode conflicts:

   • Symptom: Sticky background clashes with Filament’s dark mode.
   • Fix: Set background: 'auto' in config or override per-column:

     StickyColumn::make('id')->sticky(background: 'bg-white dark:bg-gray-900'),
     

Debugging

• Inspect DOM: Verify data-sticky="left/right" exists on <th>/<td> (not nested elements). Use browser dev tools to check computed styles.

• Shadow visibility: If scroll shadows (sticky-shadow-active) don’t appear, ensure:

  • shadow: true in config.
  • No conflicting CSS (e.g., overflow: hidden on parent).

• Livewire updates: If stickiness breaks after Livewire interactions, manually refresh:

  window.FilamentStickyColumns.refresh();
  

Extension Points

1. Custom CSS: Extend the package’s CSS by overriding classes in your theme:

   /* resources/css/filament/admin/theme.css */
   .fi-ta-sticky-left {
       @apply bg-blue-50 dark:bg-blue-900/30; /* Custom dark mode */
   }
   

2. JS hooks: Extend functionality via Livewire hooks:

   Livewire.hook('commit', () => {
       window.FilamentStickyColumns.refresh();
       // Custom logic (e.g., log offsets)
       console.log('Sticky columns refreshed');
   });
   

3. Config overrides: Publish and modify the config for global settings:

   php artisan vendor:publish --tag="filament-sticky-columns-config"
   

   Example override:

   'shadow_color' => 'rgba(100, 100, 100, 0.2)', // Custom shadow
   

Pro Tips

• Performance: For large tables, disable shadows (shadow: false) to reduce repaints:

  // config/filament-sticky-columns.php
  'shadow' => env('FILAMENT_STICKY_SHADOWS') === 'true',
  

• Responsive design: Combine with Filament’s hiddenOn to hide sticky columns on mobile:

  StickyColumn::make('id')->hiddenOn(['mobile'])->sticky(),
  

• Accessibility: Ensure sticky columns don’t violate screen reader expectations by adding ARIA labels:

  StickyColumn::make('status')->sticky()->extraAttributes(['aria-label' => 'Status column']),