Filament Hover Image Column Laravel Package

Getting Started

Minimal Setup

1. Installation: Run composer require tinusg/filament-hover-image-column in your Laravel project.
2. Replace ImageColumn: Swap any existing ImageColumn in your Filament table with HoverImageColumn:

   use TinusG\FilamentHoverImageColumn\HoverImageColumn;
   
   HoverImageColumn::make('avatar')
       ->circular();
   

3. Test: Hover over the thumbnail in your Filament table to see the preview card appear.

First Use Case

• Enhance User Experience: Replace a standard ImageColumn for profile avatars or product images to provide a richer hover preview without additional UI clutter.

Implementation Patterns

Common Workflows

1. Basic Replacement:

   HoverImageColumn::make('image')
       ->label('Product Image')
       ->width(50);
   

   • Directly replaces ImageColumn with hover functionality.

2. Dynamic Previews:

   HoverImageColumn::make('thumbnail')
       ->previewUrl(fn ($record) => $record->high_res_image_url)
       ->previewSize(600, 400);
   

   • Useful for e-commerce or media-heavy applications where high-res previews are needed.

3. Computed State:

   HoverImageColumn::make('media.source_url')
       ->state(fn ($record) => $record->getPrimaryMediaUrl())
       ->circular();
   

   • Ideal for relationships or nested data where the image URL isn’t directly on the model.

4. Conditional Previews:

   HoverImageColumn::make('cover_image')
       ->preview(fn ($record) => $record->has_high_res_image ? true : false)
       ->previewSize(800);
   

   • Disable previews for records lacking high-res images.

Integration Tips

• Styling: Use Filament’s built-in styling methods (width, height, circular) to match your app’s design.
• Performance: For large datasets, lazy-load previews or use preview(false) for non-critical images.
• Responsive Design: Test preview behavior on mobile devices; adjust previewSize as needed.

Gotchas and Tips

Pitfalls

1. Missing Image URLs:
   • If state() returns null or an invalid URL, the column renders as a broken image. Always validate URLs:

     ->state(fn ($record) => $record->image_url ?? null)
     

2. Preview Overlap:
   • On small screens, hover previews may overlap other UI elements. Test responsiveness and adjust previewSize or CSS.
3. Caching Issues:
   • If previews don’t update after changes, clear Filament’s view cache:

     php artisan filament:cache-reset
     

Debugging

• Inspect the DOM: Use browser dev tools to verify the preview card’s HTML structure and apply custom CSS if needed.
• Log State Values:

  ->state(fn ($record) => {
      \Log::debug('Image URL:', [$record->image_url]);
      return $record->image_url;
  })
  

Extension Points

1. Custom Preview Content: Override the default preview template by publishing and modifying the view:

   php artisan vendor:publish --tag=filament-hover-image-column:views
   

   Edit resources/views/vendor/filament-hover-image-column/preview.blade.php.

2. Animation: Add CSS transitions to the preview card for smoother hover effects:

   .filament-hover-image-preview {
       transition: all 0.3s ease;
   }
   

3. Accessibility: Ensure previews include aria-label or alt text for screen readers:

   ->previewAltText('Larger image preview')