Filament Input Loading Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require coringaawc/filament-input-loading in your Laravel project. No additional configuration is required—auto-discovery handles registration.

2. First Use Case Replace your existing TextInput import in a Filament form with:

   use CoringaWc\FilamentInputLoading\TextInput;
   

   Then use lazy() or debounce() on the input as usual:

   TextInput::make('search')
       ->debounce(500)
       ->live(onBlur: true),
   

   The loading spinner will now appear inside the input during server processing.

3. Where to Look First

   • README.md: Focus on the "Usage" section for quick implementation.
   • Source Code: Check src/TextInput.php for customization options (e.g., spinner color, size).
   • Filament Docs: Refer to Filament Forms for lazy()/debounce() behavior.

Implementation Patterns

Usage Patterns

1. Basic Integration Replace Filament\Forms\Components\TextInput with CoringaWc\FilamentInputLoading\TextInput in your form builder. No other changes are needed for core functionality.

2. Conditional Loading Use live() modifiers to control when the spinner appears:

   TextInput::make('query')
       ->debounce(300)
       ->live(onBlur: true, unlessBlank: true),
   

   • unlessBlank: Spinner only shows if the input has content.
   • onBlur: Spinner triggers on field blur (useful for search-as-you-type).

3. Customizing the Spinner Override the default spinner via the getSpinnerView() method in your form:

   TextInput::make('custom')
       ->debounce(500)
       ->extraAttributes(['data-spinner-color' => 'red']);
   

   Extend the TextInput class to modify the spinner template (see Gotchas).

4. Integration with Other Filament Components Combine with Select, MultiSelect, or Toggle by extending their classes similarly (though this package only modifies TextInput by default).

5. Dynamic Forms For dynamic forms (e.g., FormBuilder), ensure the custom TextInput is registered in your form’s getComponents() method:

   public static function getComponents(): array {
       return [
           TextInput::make('dynamic_field')->debounce(500),
       ];
   }
   

Workflows

• Search Functionality Use debounce(300) for search inputs to reduce server load while providing real-time feedback.

  TextInput::make('search_term')
      ->debounce(300)
      ->live(onChange: true),
  

• Form Validation Feedback Pair with live(onBlur: true) to show validation errors and loading spinners during async validation:

  TextInput::make('email')
      ->debounce(500)
      ->rules(['email'])
      ->live(onBlur: true),
  

• API-Driven Forms For API-heavy forms, use lazy() to trigger updates only when the input loses focus:

  TextInput::make('api_key')
      ->lazy()
      ->live(onBlur: true),
  

Integration Tips

1. Livewire Hooks If you need to customize spinner behavior, hook into Livewire’s updated events:

   protected function updated($property) {
       if (str_contains($property, 'search_')) {
           // Custom logic for search fields
       }
   }
   

2. Tailwind CSS The spinner uses Tailwind classes (animate-spin). Customize via your tailwind.config.js:

   module.exports = {
       theme: {
           extend: {
               colors: {
                   spinner: '#ef4444', // Example: Red spinner
               },
           },
       },
   };
   

3. Testing Test loading states with Livewire’s call() method:

   $this->call('search', ['query' => 'test']);
   $this->assertSee('animate-spin'); // Verify spinner appears
   

Gotchas and Tips

Pitfalls

1. Filament Version Mismatch

   • Error: Class 'Filament\Forms\Components\TextInput' not found.
   • Fix: Ensure you’re using Filament v2 (this package is incompatible with v3+). Check your composer.json:

     "require": {
         "filament/filament": "^2.0"
     }
     

2. Spinner Not Appearing

   • Cause: Missing live() modifier or incorrect debounce()/lazy() usage.
   • Debug: Verify the input has a wire:model.lazy or wire:model.debounce attribute in the rendered HTML.

3. CSS Conflicts

   • Issue: Spinner overlaps with input text or is invisible.
   • Fix: Override the spinner’s z-index in your CSS:

     .filament-input-loading__spinner {
         z-index: 10;
     }
     

4. Performance Overhead

   • Risk: Excessive debounce values (e.g., 100ms) may cause UI jank.
   • Tip: Use debounce(300) or higher for search inputs to balance responsiveness and server load.

Debugging

1. Inspect Rendered HTML Check if the spinner’s SVG/HTML is present in the input:

   <div class="filament-input-loading__spinner">
       <svg class="animate-spin" ...></svg>
   </div>
   

   If missing, the TextInput replacement wasn’t applied correctly.

2. Livewire Logs Enable Livewire logging to debug live() updates:

   Livewire::configureLogging();
   

   Check storage/logs/livewire.log for update events.

3. Blade Template Overrides If you’ve customized Filament’s text-input.blade.php, ensure the spinner’s container (filament-input-loading__spinner) isn’t removed.

Tips

1. Extending the Spinner Override the spinner’s view by publishing the package’s assets:

   php artisan vendor:publish --tag=filament-input-loading-views
   

   Then modify resources/views/vendor/filament-input-loading/spinner.blade.php.

2. Accessibility Add aria-busy to the input for screen readers:

   TextInput::make('search')
       ->debounce(500)
       ->extraAttributes(['aria-busy' => 'false'])
       ->live(onChange: true),
   

   Update aria-busy dynamically in your Livewire component:

   public function updatedSearch($value) {
       $this->dispatch('set-aria-busy', busy: true);
       // ... async logic
       $this->dispatch('set-aria-busy', busy: false);
   }
   

3. Dark Mode Support Ensure the spinner’s color contrasts in dark mode. Use Tailwind’s dark: variant:

   .filament-input-loading__spinner {
       color: theme('colors.white');
   }
   .dark .filament-input-loading__spinner {
       color: theme('colors.gray.300');
   }
   

4. Localization The spinner has no text, but if you add a label (e.g., "Loading..."), translate it:

   TextInput::make('query')
       ->debounce(500)
       ->placeholder(__('Loading...')),
   

5. Server-Side Logic For long-running operations, combine with Livewire’s wire:loading state:

   public function updatedSearch($query) {
       $this->searching = true;
       // Simulate delay
       sleep(2);
       $this->searching = false;
   }
   

   @if($this->searching)
       <div class="spinner"></div>
   @endif
   

6. Package Updates Monitor for breaking changes in Filament v2.x updates. Test after major Filament releases.