Filament Icon Picker Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require fawaziwalewa/filament-icon-picker
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="FawaziWalewa\FilamentIconPicker\FilamentIconPickerServiceProvider"
   

2. First Use Case Add the field to a Filament form/resource:

   use FawaziWalewa\FilamentIconPicker\Fields\IconPicker;
   
   IconPicker::make('icon')
       ->iconSets(['heroicons', 'lucide'])
       ->required()
   

3. Where to Look First

   • Config File: config/filament-icon-picker.php (for global defaults)
   • Field API Docs: Focus on iconSets(), searchable(), and columns() methods
   • Demo: Check the package's docs/ folder for screenshots and examples

Implementation Patterns

Core Workflows

1. Basic Icon Selection

   IconPicker::make('icon')
       ->iconSets(['heroicons:solid', 'lucide:outline'])
       ->default('heroicons:home')
   

2. Multi-Column Layout

   IconPicker::make('icon')
       ->columns(4) // Adjusts grid layout
       ->searchable() // Enables search bar
   

3. Dynamic Icon Sets

   // Load sets dynamically based on user role
   IconPicker::make('icon')
       ->iconSets(fn() => auth()->user()->can('admin') ? ['heroicons', 'lucide', 'font-awesome'] : ['heroicons', 'lucide'])
   

4. Integration with Filament Tables

   // Display icons in a table column
   use FawaziWalewa\FilamentIconPicker\Columns\IconColumn;
   
   IconColumn::make('icon')
       ->iconSets(['heroicons', 'lucide'])
       ->size('sm') // Optional: 'xs', 'sm', 'md', 'lg'
   

5. Custom Icon Sets

   // Register a custom icon set (e.g., from a CDN)
   IconPicker::make('icon')
       ->iconSets([
           'custom' => [
               'path' => 'https://cdn.example.com/icons',
               'prefix' => 'custom-',
               'icons' => ['home', 'settings', 'user'],
           ],
       ]);
   

6. Validation & Rules

   IconPicker::make('icon')
       ->rules([
           Rule::required(),
           Rule::in(['heroicons:home', 'lucide:settings']),
       ])
   

Pro Tips

• Reuse Icon Sets: Define sets in config and reference them:

  IconPicker::make('icon')
      ->iconSets(config('filament-icon-picker.sets.admin'))
  

• Livewire Component: Extend the picker for custom logic:

  use FawaziWalewa\FilamentIconPicker\Components\IconPickerWidget;
  
  IconPickerWidget::make('custom_icon')
      ->iconSets(['heroicons'])
      ->extraAttribute('data-custom', 'value');
  

• Dark Mode: Automatically inherits Filament’s dark mode via Alpine.js.

Gotchas and Tips

Common Pitfalls

1. Icon Set Not Found

   • Cause: Misspelled set name (e.g., heroicon vs heroicons).
   • Fix: Verify set names in config/filament-icon-picker.php or use dd(FilamentIconPicker::getAvailableSets()) to debug.

2. Icons Not Loading

   • Cause: CDN blocked or missing public_path() in custom sets.
   • Fix: For local assets, use:

     'path' => public_path('vendor/icons'),
     

   • Ensure filament-icon-picker:assets is published if using custom assets.

3. Search Not Working

   • Cause: searchable() not called or Alpine.js conflict.
   • Fix: Wrap in a livewire:ignore block if needed:

     <div x-data x-ignore>
         {{ $this->iconPicker }}
     </div>
     

4. Performance with Large Sets

   • Cause: Too many icons slow down rendering.
   • Fix: Limit sets or use lazy-loading:

     IconPicker::make('icon')
         ->iconSets(['heroicons:solid' => ['home', 'settings']]) // Subset
     

Debugging

• Log Available Sets:

  dd(FilamentIconPicker::getAvailableSets());
  

• Inspect Alpine.js State: Open browser dev tools (F12) and check the Alpine store for iconPicker data.

Extension Points

1. Custom Icon Rendering Override the default icon rendering in a service provider:

   FilamentIconPicker::macro('renderIcon', function ($icon, $size = 'md') {
       return "<svg>...</svg>"; // Custom SVG
   });
   

2. Add New Icon Sets Extend the IconSet class or publish the config:

   // config/filament-icon-picker.php
   'sets' => [
       'custom' => [
           'path' => 'https://cdn.example.com',
           'prefix' => 'custom-',
           'icons' => ['icon1', 'icon2'],
       ],
   ],
   

3. Localization Translate labels/placeholders via Filament’s localization system:

   IconPicker::make('icon')
       ->label(__('filament-icon-picker::fields.icon.label'))
       ->placeholder(__('filament-icon-picker::fields.icon.placeholder'))
   

Config Quirks

• Default Sets: The package ships with heroicons and lucide pre-configured. Disable them in config if not needed:

  'enabled_sets' => ['heroicons:solid', 'lucide:outline'],
  

• Asset Publishing: Run php artisan filament-icon-picker:assets to publish JS/CSS if customizing styles.

Performance

• Debounce Search: Adjust the search debounce time in config:

  'search_debounce' => 300, // ms
  

• Preload Icons: For critical paths, preload icons in a blade template:

  @foreach(config('filament-icon-picker.sets.heroicons.icons') as $icon)
      <link rel="preload" href="{{ asset("vendor/filament-icon-picker/icons/{$icon}.svg") }}" as="image">
  @endforeach