Filament Lightbox Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require njxqlus/filament-lightbox
   

   Publish the config (optional but recommended for customization):

   php artisan vendor:publish --tag="filament-lightbox-config"
   

2. First Use Case: Replace a standard ImageEntry in a Filament Infolist with LightboxImageEntry:

   use Njxqlus\Filament\Components\Infolists\LightboxImageEntry;
   
   LightboxImageEntry::make('Image')
       ->href($model->image_url)
       ->image($model->image_url)
       ->imageWidth(300) // Optional: Set thumbnail width
       ->imageHeight(300) // Optional: Set thumbnail height
   

3. Spatie Media Library Integration: For Spatie Media Library models, use the LightboxMediaEntry:

   use Njxqlus\Filament\Components\Infolists\LightboxMediaEntry;
   
   LightboxMediaEntry::make('Image')
       ->model($model)
       ->attribute('image') // Spatie Media Library attribute
   

Implementation Patterns

Common Workflows

1. Basic Lightbox in Infolists

Replace any ImageEntry with LightboxImageEntry to enable lightbox functionality:

Infolist::make()
    ->schema([
        LightboxImageEntry::make('Profile Picture')
            ->href($user->profile_photo_url)
            ->image($user->profile_photo_url),
    ]);

2. Dynamic Lightbox for Collections

Use LightboxImageEntry in Table columns for clickable thumbnails:

use Njxqlus\Filament\Tables\Columns\LightboxImageColumn;

Tables\Columns\LightboxImageColumn::make('thumbnail')
    ->href(fn ($record) => $record->image_url)
    ->image(fn ($record) => $record->image_url)
    ->width(80)
    ->height(80),

3. Spatie Media Library Integration

Leverage LightboxMediaEntry for models using Spatie Media Library:

LightboxMediaEntry::make('Cover Image')
    ->model($post)
    ->attribute('cover_image') // Spatie attribute
    ->openable() // Optional: Allow lightbox to open on click
    ->width(400)
    ->height(300),

4. Custom Lightbox Configuration

Publish the config (filament-lightbox.php) to customize:

// config/filament-lightbox.php
return [
    'lightbox_options' => [
        'zoom' => true,
        'share' => false,
        'counter' => true,
    ],
];

5. Lightbox in Forms

Use LightboxImageEntry in Form sections for previewing uploaded images:

Form::make()
    ->schema([
        LightboxImageEntry::make('Preview')
            ->href(fn ($record) => $record->image_url ?? null)
            ->image(fn ($record) => $record->image_url ?? null)
            ->hiddenLabel(),
    ]);

Integration Tips

• Lazy Loading: Use ->lazy() on LightboxImageEntry for better performance with large datasets.
• Responsive Design: Adjust width and height based on screen size using Filament’s responsive helpers:

  ->width(200)->responsive(['md' => 300, 'lg' => 400])
  

• Fallback for Missing Images: Provide a default image URL:

  ->image(fn ($record) => $record->image_url ?? asset('images/default.png'))
  

• Lightbox for Non-Image Media: Extend the package to support PDFs or videos by customizing the Lightbox component (see Gotchas).

Gotchas and Tips

Pitfalls

1. Missing href Attribute:

   • Error: Lightbox won’t work if href() is not set.
   • Fix: Always include ->href() with a valid URL, even if it’s the same as the image URL.

     ->href($model->image_url)
     ->image($model->image_url)
     

2. Spatie Media Library Caching:

   • Issue: If using Spatie Media Library, ensure the model’s getFirstMediaUrl() or similar method returns the correct URL. Cached thumbnails may not update immediately.
   • Fix: Clear the cache or regenerate thumbnails:

     php artisan cache:clear
     php artisan media:regenerate-thumbnails
     

3. CSS Conflicts:

   • Issue: Lightbox styles may conflict with Filament’s default CSS, especially in dark mode.
   • Fix: Override styles in your app’s CSS:

     .filament-lightbox .lb-image {
         filter: brightness(0) invert(1); /* Dark mode fix */
     }
     

4. Lightbox Not Opening:

   • Common Causes:
     • Missing href or image attributes.
     • JavaScript errors (check browser console).
     • Ad blockers blocking lightbox scripts.
   • Debugging:

     // Check if lightbox is initialized
     console.log(document.querySelectorAll('.filament-lightbox'));
     

Tips

1. Custom Lightbox Templates:

   • Publish the views (php artisan vendor:publish --tag="filament-lightbox-views") and modify resources/views/vendor/filament-lightbox/lightbox.blade.php to add custom buttons or toolbars.

2. Extending for Non-Image Media:

   • To support PDFs or videos, create a custom component extending Lightbox:

     namespace App\Filament\Components;
     
     use Njxqlus\Filament\Components\Lightbox;
     
     class CustomLightbox extends Lightbox
     {
         protected static string $view = 'filament-lightbox::custom-lightbox';
     
         public static function make(string $url): static
         {
             return new static($url);
         }
     }
     

3. Performance Optimization:

   • Use ->lazy() for lightbox entries in tables to defer initialization:

     LightboxImageColumn::make('Image')
         ->href(fn ($record) => $record->image_url)
         ->image(fn ($record) => $record->image_url)
         ->lazy(),
     

4. Accessibility:

   • Add ARIA attributes for better accessibility:

     LightboxImageEntry::make('Image')
         ->href($url)
         ->image($url)
         ->ariaLabel('View full-size image'),
     

5. Debugging Lightbox Events:

   • Listen for lightbox events (e.g., lightbox:open) by extending the JavaScript:

     document.addEventListener('lightbox:open', (e) => {
         console.log('Lightbox opened:', e.detail);
     });
     

6. Config Overrides:

   • Override lightbox options globally in config/filament-lightbox.php:

     'lightbox_options' => [
         'zoom' => false,
         'counter' => false,
         'close' => true,
         'closeOnClick' => 'node', // 'node', 'outside', or 'background'
     ],
     

7. Testing:

   • Test lightbox functionality in headless browsers (e.g., Laravel Dusk) by simulating clicks:

     $this->click('.filament-lightbox-trigger');
     $this->assertSee('Lightbox content');