Getting Started

Minimal Setup

Installation

composer require tomatophp/filament-icons

Publish the config (optional, but recommended for customization):

php artisan vendor:publish --provider="TomatoPHP\FilamentIcons\FilamentIconsServiceProvider"

Register the Icon Provider In your app/Providers/AppServiceProvider.php or a dedicated Filament service provider:

use TomatoPHP\FilamentIcons\FilamentIconsServiceProvider;

public function register()
{
    if ($this->app->runningInConsole()) {
        $this->app->register(FilamentIconsServiceProvider::class);
    }
}

First Use Case: Icon Picker in a Form Add the icon picker to a Filament form field:

use TomatoPHP\FilamentIcons\Fields\IconPicker;

IconPicker::make('icon')
    ->label('Select an Icon')
    ->required(),

Where to Look First

Documentation: GitHub README (includes screenshots and basic usage).
Config File: config/filament-icons.php (customize allowed icon sets, default sizes, etc.).
Field API: Explore IconPicker methods (e.g., allowedSets(), size(), searchable()).

Table Columns: Use IconColumn for displaying icons in table rows:

use TomatoPHP\FilamentIcons\Columns\IconColumn;

IconColumn::make('icon')
    ->label('Status')
    ->size('sm'),

Implementation Patterns

Workflows

Consistent Icon Usage Across Forms/Tables Reuse the same icon sets (e.g., fa, heroicon, tabler) in both forms and tables by leveraging the provider’s shared configuration.
```
// In config/filament-icons.php
'allowed_sets' => ['fa', 'heroicon', 'tabler'],
```

Dynamic Icon Selection Use the IconPicker in livewire forms to let users select icons dynamically:

IconPicker::make('notification_icon')
    ->allowedSets(['fa', 'heroicon'])
    ->size('lg')
    ->searchable(),

Conditional Icon Rendering Combine with Filament’s statePath or using() to render icons conditionally in tables:

IconColumn::make('status')
    ->statePath('is_active')
    ->trueIcon('heroicon-o-check-circle')
    ->falseIcon('heroicon-o-x-circle')
    ->size('sm'),

Custom Icon Sets Extend the package by adding a custom icon set:

// In a service provider
FilamentIcons::extend('custom', function () {
    return new \TomatoPHP\FilamentIcons\Sets\CustomIconSet();
});

Integration Tips

Theme Consistency: Ensure your Filament theme’s CSS variables (e.g., --color-primary) align with the icon set’s styling (e.g., Heroicons use currentColor by default).
Performance: Lazy-load icon sets if using many (e.g., only load fa and heroicon on pages where they’re needed).

Localization: Translate icon labels or tooltips using Filament’s __() helper:

IconPicker::make('icon')
    ->label(__('filament-icons::labels.icon'))
    ->placeholder(__('filament-icons::placeholders.select_icon')),

Gotchas and Tips

Pitfalls

Icon Set Conflicts
- Issue: Mixing icon sets (e.g., Font Awesome + Heroicons) may cause duplicate class names or styling clashes.
- Fix: Use unique prefixes in your config or CSS:
```
/* Target specific icon sets */
.fa-solid { color: var(--color-primary); }
.heroicon-o-check { color: var(--color-success); }
```
Missing Icon Sets
- Issue: If an icon set isn’t registered, the picker/table column will fail silently.
- Fix: Verify allowed_sets in config/filament-icons.php and run:
```
php artisan filament-icons:install
```
  (if the package includes an installer command).
Caching Headaches
- Issue: Changes to icon sets or config may not reflect due to Filament’s asset caching.
- Fix: Clear Filament’s cache:
```
php artisan filament:cache-clear
```
  Or disable caching temporarily during development:
```
FilamentIcons::disableCache();
```
Responsive Sizing
- Issue: Icons may appear too large/small on mobile.
- Fix: Use responsive sizing options:
```
IconColumn::make('icon')
    ->size(['sm' => '1em', 'md' => '1.5em', 'lg' => '2em']),
```

Debugging

Check Registered Sets: Dump available icon sets in a route or Tinker:
```
dd(\TomatoPHP\FilamentIcons\Facades\FilamentIcons::getSets());
```
Inspect Rendered HTML: Use browser dev tools to verify icon classes are correct (e.g., fa fa-solid fa-user for Font Awesome).
Log Configuration: Add debug logs to config/filament-icons.php:
```
'debug' => env('FILAMENT_ICONS_DEBUG', false),
```

Extension Points

Custom Icon Sets Create a new set by extending TomatoPHP\FilamentIcons\Contracts\IconSet:

namespace App\FilamentIcons;

use TomatoPHP\FilamentIcons\Contracts\IconSet;

class MyIconSet implements IconSet {
    public function getIcons(): array {
        return ['my-icon' => 'My Icon'];
    }

    public function getDisplayName(): string {
        return 'My Icons';
    }
}

FilamentIcons::extend('my-icons', function () {
    return new MyIconSet();
});

Override Default Provider Replace the default icon provider entirely by binding a custom class to the filament-icons.provider tag:

$this->app->bind(
    \TomatoPHP\FilamentIcons\Contracts\IconProvider::class,
    \App\Providers\CustomIconProvider::class
);

Add Custom Attributes Extend the IconPicker or IconColumn to support custom HTML attributes:
```
IconPicker::make('icon')
    ->extraAttributes(['data-tooltip' => 'Click to edit']),
```

Pro Tips

Icon Preview in Picker: Use the preview method to show icons inline:
```
IconPicker::make('icon')
    ->preview(),
```

Bulk Icon Updates: Combine with Filament’s BulkAction to update icons for multiple records:

use Filament\Tables\Actions\BulkAction;

BulkAction::make('updateIcon')
    ->action(function (Collection $records) {
        $records->update(['icon' => 'heroicon-o-pencil']);
    }),

Dark Mode Support: Ensure your icon set supports dark mode (e.g., Heroicons use currentColor). Test with Filament’s dark mode toggle:
```
// In config/filament.php
'dark_mode' => true,
```

Filament Icons Laravel Package