Filament Icon Picker Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require wallacemartinss/filament-icon-picker
   

2. Install icon packages (interactive installer recommended):

   php artisan filament-icon-picker:install-icons
   

3. Add views to Tailwind:

   /* resources/css/filament/admin/theme.css */
   @source '../../../../vendor/wallacemartinss/filament-icon-picker/resources/views/**/*';
   

4. Build assets:

   npm run build
   

First Use Case

Add an icon picker to a Form Field in a Filament resource:

use Wallacemartinss\FilamentIconPicker\Forms\Components\IconPickerField;

public static function form(Form $form): Form
{
    return $form->schema([
        IconPickerField::make('icon')
            ->label('Select an Icon')
            ->searchable(),
    ]);
}

Implementation Patterns

Common Workflows

1. Form Integration

• Basic Usage:

  IconPickerField::make('icon')
      ->required()
      ->searchable()
      ->allowedSets(['heroicons', 'phosphor-icons']);
  

• Dynamic Validation:

  IconPickerField::make('icon')
      ->rules(fn (Form $form) => [
          'required' => $form->getState()->is_active,
      ]);
  

2. Table Column Styling

• Conditional Styling:

  IconPickerColumn::make('status_icon')
      ->color(fn ($record) => $record->is_active ? 'success' : 'danger')
      ->size(fn ($record) => $record->is_premium ? 'xl' : 'md')
      ->animation(fn ($record) => $record->is_loading ? 'spin' : null);
  

• Fixed Icons (No DB Column):

  IconPickerColumn::make('type_indicator')
      ->icon('heroicon-o-star')
      ->warning()
      ->extraSmall();
  

3. Infolist Display

• Read-Only Icons:

  IconPickerEntry::make('avatar_icon')
      ->icon(fn ($record) => "heroicon-o-$record->role")
      ->color('primary')
      ->showIconName(false);
  

4. Icon Enums (Type-Safe)

• Generated Enums:

  use Wallacemartinss\FilamentIconPicker\Enums\Heroicons;
  
  // Navigation icon
  protected static string|BackedEnum|null $navigationIcon = Heroicons::OutlinedStar;
  
  // Action icon
  Action::make('export')
      ->icon(Heroicons::OutlinedArrowDownTray);
  

• Dynamic Enums:

  use Wallacemartinss\FilamentIconPicker\Enums\Icon;
  
  public static function getNavigationIcon(): ?string
  {
      return Icon::phosphor('gear', 'duotone');
  }
  

5. Performance Optimization

• Cache Icons:

  php artisan icons:cache
  

• Lazy-Loading: The picker uses infinite scroll by default—no extra config needed.

Integration Tips

With Filament Actions

use Wallacemartinss\FilamentIconPicker\Enums\PhosphorIcons;

Action::make('approve')
    ->icon(PhosphorIcons::CheckCircle)
    ->color('success')
    ->requiresConfirmation();

With Filament Widgets

use Wallacemartinss\FilamentIconPicker\Enums\MaterialIcons;

Widget::make('status_widget')
    ->icon(fn () => MaterialIcons::Error->value)
    ->color(fn () => $this->getStatusColor())
    ->spin(fn () => $this->isLoading());

Customizing Modal Size

IconPickerField::make('icon')
    ->modalSize('4xl') // Default: '3xl'
    ->columns(6);     // Override grid columns (default: 6)

Extending Icon Sets

1. Add a new icon package:

   composer require afatmustafa/blade-hugeicons
   

2. Regenerate enums:

   php artisan filament-icon-picker:generate-enums --all
   

3. Update config (config/filament-icon-picker.php):

   'allowed_sets' => ['heroicons', 'hugeicons', 'phosphor-icons'],
   

Gotchas and Tips

Pitfalls

1. Missing Icon Sets

   • Issue: Icons don’t appear in the picker.
   • Fix: Ensure you’ve installed at least one icon package via php artisan filament-icon-picker:install-icons or manually via Composer.
   • Debug: Run php artisan filament-icon-picker:install-icons --list to check installed sets.

2. Tailwind Scanning Errors

   • Issue: Icons render as empty squares.
   • Fix: Verify @source directive is added to resources/css/filament/admin/theme.css and run npm run build.

3. Enum Generation Conflicts

   • Issue: php artisan filament-icon-picker:generate-enums fails.
   • Fix:
     • Delete app/Enums (if auto-generated) or manually resolve naming conflicts.
     • Use --force flag: php artisan filament-icon-picker:generate-enums --force.

4. Caching Issues

   • Issue: Changes to icons or config aren’t reflected.
   • Fix: Clear caches:

     php artisan optimize:clear
     php artisan view:clear
     

5. Infinite Scroll Not Working

   • Issue: Picker loads all icons at once.
   • Fix: Ensure no JavaScript errors in browser console. Check for conflicts with other Filament plugins.

Debugging Tips

1. Log Available Icons

   // Dump all registered icons
   dd(\Wallacemartinss\FilamentIconPicker\Facades\Icon::all());
   

2. Check Installed Sets

   php artisan filament-icon-picker:install-icons --list
   

3. Inspect Modal Rendering

   • Open browser dev tools (F12) and check the Network tab for failed requests to /filament-icon-picker/icons.

4. Validate Icon Names

   • Use the Icon helper to test icon rendering:

     echo \Wallacemartinss\FilamentIconPicker\Enums\Icon::heroicon('star', 'outlined');
     

Configuration Quirks

1. allowed_sets in Config

   • Behavior: Restricts picker to specified sets (e.g., ['heroicons', 'phosphor-icons']).
   • Default: [] (allows all installed sets).
   • Note: Use set names (e.g., heroicons), not package names (e.g., blade-heroicons).

2. Modal Size Limits

   • Options: sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl, 7xl.
   • Default: 3xl.
   • Tip: Use 4xl for large icon libraries (e.g., Material Design).

3. Dynamic Methods

   • Closures: Accept fn ($record) => ... for dynamic sizing/coloring.
   • Example:

     IconPickerColumn::make('icon')
         ->size(fn ($record) => $record->priority === 'high' ? 'xl' : 'md')
         ->color(fn ($record) => $record->is_urgent ? 'danger' : 'gray');
     

4. Icon Preview in Forms

   • Behavior: The picker shows a preview of the selected icon in the field.
   • Customization: Override the preview template in resources/views/vendor/filament-icon-picker/preview.blade.php.

Extension Points

1. Custom Icon Sets

   • Approach: Extend the IconSet class to support non-blade-icons packages.
   • Example:

     // app/Providers/FilamentIconPickerServiceProvider.php
     public function boot(): void
     {
         $this->app->make(\Wallacemartinss\FilamentIconPicker\Contracts\IconRegistry::class)
             ->registerSet(new CustomIconSet());
     }
     

2. Override Blade Views

   • Location: Copy vendor views to resources/views/vendor/filament-icon-picker/:

     cp -r vendor/wallacemartinss/filament-icon-picker/resources/views/* resources/views/vendor/filament-icon-picker/
     

   • Modify: Edit modal.blade.php or preview.blade.php for custom UI.

3. Add Custom Animations

   • Approach: Extend the IconPickerColumn/IconPickerEntry classes.
   • Example: