Filament Icon Picker Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require guava/filament-icon-picker
   php artisan filament:assets
   

2. Configure Theme: Add to your resources/css/theme.css:

   @source '../../../../vendor/guava/filament-icon-picker/resources/**/*';
   

3. First Use Case: Add to a Filament form schema:

   use Guava\IconPicker\Forms\Components\IconPicker;
   
   IconPicker::make('icon')
       ->label('Select an icon')
       ->required();
   

Where to Look First

• Documentation: Focus on the README for installation and basic usage.
• Source: Check src/Forms/Components/IconPicker.php for field customization options.
• Table Column: Review src/Tables/Columns/IconColumn.php for display logic.

Implementation Patterns

Common Workflows

1. Form Integration:

   // Basic usage
   IconPicker::make('icon')
       ->sets(['heroicons', 'tabler'])
       ->gridSearchResults();
   
   // With validation
   IconPicker::make('icon')
       ->required()
       ->rule('required|string')
       ->maxLength(50);
   

2. Table Display:

   use Guava\IconPicker\Tables\Columns\IconColumn;
   
   $table->columns([
       IconColumn::make('icon')
           ->label('Icon')
           ->placeholder('No icon selected'),
   ]);
   

3. Frontend Rendering:

   <x-icon :name="$model->icon" />
   

Integration Tips

• Custom Icon Sets: Ensure your blade-icons sets are installed (e.g., blade-icons/heroicons).
• Livewire Components: Works seamlessly with Filament's Livewire-based forms.
• Resource Customization: Extend the field in a resource class:

  public static function form(Form $form): Form {
      return $form->schema([
          IconPicker::make('icon')
              ->sets(['custom-set'])
              ->listSearchResults(),
      ]);
  }
  

Advanced Patterns

• Dynamic Set Loading: Use ->sets() to restrict available icons per context.
• Conditional Display: Combine with Filament's conditional logic:

  IconPicker::make('icon')
      ->visible(fn ($record) => $record->is_customizable),
  

Gotchas and Tips

Pitfalls

1. Missing Assets:

   • Forgetting php artisan filament:assets after installation causes broken UI.
   • Fix: Run the command and clear cache (php artisan optimize).

2. Icon Set Mismatch:

   • Using an icon set not installed via blade-icons (e.g., heroicons without blade-icons/heroicons).
   • Fix: Install the required package:

     composer require blade-icons/heroicons
     

3. Theme CSS Not Loaded:

   • Icons may not render if @source directive is missing in theme.css.
   • Fix: Verify the path in resources/css/theme.css.

4. Null Icons in Tables:

   • If an icon is deleted from the set but remains in the database, IconColumn may show null.
   • Fix: Use ->placeholder() or handle nulls in Blade:

     <x-icon :name="$model->icon ?? 'heroicons-outline-x-circle'" />
     

Debugging Tips

• Check Available Sets:

  // Log available icon sets
  \Log::info(\Guava\IconPicker\IconManager::getAvailableSets());
  

• Inspect Icon Names: The database stores full names (e.g., heroicons-outline-shopping-cart). Verify these match your blade-icons set.

Extension Points

1. Custom Search Views: Override the search result views in resources/views/vendor/guava/icon-picker/. Example: Copy resources/views/vendor/guava/icon-picker/search-results-grid.blade.php to your project.

2. Icon Manager: Extend \Guava\IconPicker\IconManager to add custom icon sets or logic:

   // app/Providers/AppServiceProvider.php
   public function boot() {
       \Guava\IconPicker\IconManager::extend('custom-set', function () {
           return collect([/* custom icons */]);
       });
   }
   

3. Livewire Config: For large icon sets, adjust payloads.max_calls in config/livewire.php:

   'payloads' => [
       'max_calls' => 100, // Increase if icons lag
   ],
   

Performance

• Preload Icons: Use ->preload() (if supported in future versions) to cache icons on first load.
• Limit Sets: Restrict sets with ->sets(['heroicons']) to reduce payload size.

Configuration Quirks

• Filament Version Compatibility:

  • Ensure your Filament version matches the plugin version (e.g., guava/filament-icon-picker:^4.0 for Filament 5.x).
  • Fix: Check the compatibility table.

• CSS Conflicts: If icons appear misaligned, inspect the generated CSS in node_modules or override via theme.css.