Filament Lottie Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require visualbuilder/filament-lottie
   

   This auto-registers the package’s JS/CSS assets globally. Disable via config('lottie.auto_register_assets', false) if needed.

2. First Use Case:

   • Schema Component: Add a Lottie animation to a Filament form/resource schema:

     use Visualbuilder\Lottie\Components\Lottie;
     
     Lottie::make('welcome')
         ->src('lottie/welcome.lottie') // Path to your Lottie JSON file
         ->size('100px');
     

   • Blade Component: Embed animations in views:

     <x-lottie src="lottie/welcome.lottie" size="100px" />
     

3. Asset Placement:

   • Store Lottie JSON files in public/lottie/ (or a subdirectory like public/animations/).
   • Reference them via relative paths (e.g., lottie/welcome.lottie).

Implementation Patterns

Common Workflows

1. Dynamic Animations in Forms/Resources:

   • Use Lottie in schema() for visual feedback (e.g., success/error states):

     Lottie::make('success')
         ->src('lottie/success.lottie')
         ->trigger('visible') // Play when element enters viewport
         ->onComplete('event:animation-finished');
     

   • Bind to Livewire events:

     ->trigger('event:custom-event-name'); // Triggers on Livewire event dispatch
     

2. Panel-Level Defaults:

   • Override global config per panel:

     ->plugins([
         LottiePlugin::make()
             ->defaultSize('60px')
             ->defaultLoop(true),
     ]);
     

3. Blade Integration:

   • Use in custom views (e.g., landing pages, modals):

     <x-lottie
         src="lottie/loading.lottie"
         autoplay
         loop
         size="80px"
         trigger="click"
     />
     

4. Conditional Rendering:

   • Combine with Filament’s conditional logic:

     Lottie::make('conditional-animation')
         ->src(fn ($record) => $record->is_active ? 'lottie/active.lottie' : 'lottie/inactive.lottie')
         ->visible(fn ($record) => $record->has_animation);
     

Integration Tips

• Asset Optimization:
  • Preload critical Lottie files in app.blade.php:

    @if(config('lottie.auto_register_assets'))
        @preload('lottie/welcome.lottie')
    @endif
    

• Theming:
  • Override styles via resources/css/filament/lottie.css:

    .lottie-container {
        filter: drop-shadow(0 0 8px rgba(0, 0, 0, 0.3));
    }
    

• Performance:
  • Disable autoplay for offscreen animations:

    ->autoplay(false)
    ->trigger('visible');
    

  • Use respectReducedMotion() to comply with user preferences.

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • Issue: src() paths are relative to the root of the public folder. Fix: Use absolute paths (e.g., lottie/animations/welcome.lottie) or ensure files are in public/lottie/.
   • Debug: Check browser’s Network tab for 404s on .lottie files.

2. Trigger Timing:

   • Issue: trigger('mount') may not work in nested Livewire components. Fix: Use trigger('visible') or trigger('event:custom-event') with explicit dispatches.

3. Reduced Motion:

   • Issue: Animations may play despite respectReducedMotion(true). Fix: Test with prefers-reduced-motion: reduce in browser dev tools or use ->respectReducedMotion(false) for testing.

4. Livewire Events:

   • Issue: onComplete events may not fire if the component unmounts. Fix: Use wire:ignore on the container or handle cleanup in mount()/updated().

Debugging

• Console Logs:

  • Enable debug mode in config/lottie.php:

    'debug' => env('APP_DEBUG', false),
    

  • Check browser console for errors like Failed to load Lottie file.

• Common Errors:

  • Uncaught ReferenceError: DotLottiePlayer is not defined: Ensure assets are registered (check resources/dist/lottie.js exists).
  • Animation not playing: Verify autoplay and trigger settings. Test with trigger('click') manually.

Extension Points

1. Custom Triggers:

   • Extend the trigger method by publishing the config and adding new trigger handlers in resources/js/lottie.js:

     DotLottiePlayer.registerTrigger('custom', (player) => {
         // Custom logic (e.g., listen to a Livewire event)
     });
     

2. Dynamic Sources:

   • Override the src getter in a custom component:

     class DynamicLottie extends Lottie {
         public function src(): string {
             return "lottie/{$this->getKey()}.lottie";
         }
     }
     

3. Server-Side Rendering (SSR):

   • Disable Lottie in SSR builds by checking the environment:

     if (!app()->environment('ssr')) {
         Lottie::make('animation')->src('...');
     }
     

4. Local Development:

   • Symlink Lottie files for easier testing:

     ln -s /path/to/local/lottie.json public/lottie/