README

Sponsored by Tasklemon.

A beautiful, searchable icon picker field for FilamentPHP v5, built with Livewire and Alpine.js. Select from multiple icon sets including Heroicons, Lucide, and more.

Features

• 🎨 Beautiful UI - Clean, modern interface that matches Filament's design
• 🔍 Searchable - Quickly find icons with real-time search
• 📦 Multiple Icon Sets - Support for Heroicons, Lucide, Font Awesome, Bootstrap Icons, and more
• ⚡ Fast - Built with Alpine.js for instant interactions
• 🎯 Native Filament Integration - Uses Filament's icon rendering system
• 🌙 Dark Mode - Full dark mode support
• ⚙️ Configurable - Customize sets, columns, search, and more
• 🧪 Production Ready - Clean, tested, maintainable code

Requirements

• PHP 8.2+
• Laravel 12+
• FilamentPHP v5.0+
• Blade Icons (blade-ui-kit/blade-icons)

Installation

Install the package via Composer:

composer require fawaziwalewa/filament-icon-picker

Optional (recommended):

php artisan vendor:publish --tag="filament-icon-picker-config"

Optional (only if you want to override the UI):

php artisan vendor:publish --tag="filament-icon-picker-views"

Configuration

The configuration file (config/filament-icon-picker.php) controls:

• which icon sets are available and enabled
• default selected sets (sets)
• default grid columns (columns)
• default search toggle (searchable)
• placeholder text (placeholder)
• caching and endpoint behavior

Heroicons, Lucide, Font Awesome, and Bootstrap Icons are bundled as Composer dependencies of this package.

Usage

use FawazIwalewa\FilamentIconPicker\Forms\Components\IconPicker;

IconPicker::make('icon')
    ->label('Icon')
    ->required();

Sets

Sets are referenced by their config keys (from filament-icon-picker.icon_sets):

IconPicker::make('icon')
    ->sets(['heroicons', 'lucide', 'bootstrap']);

Grid + search

IconPicker::make('icon')
    ->gridColumns(8)
    ->searchable(true)
    ->placeholder('Pick an icon');

Prefix icon behavior (important)

The selected icon is always shown as the field prefix icon using Filament's input wrapper styling.

• Do not call ->prefixIcon(...) on this field.
• IconPicker::prefixIcon() is intentionally not supported and will throw.

Rendering icons

The selected value is stored as a string (e.g. heroicon-o-user, lucide-alarm-clock, bi-alarm, fas-user).

In Filament

use Filament\Tables\Columns\TextColumn;

TextColumn::make('name')
    ->icon(fn ($record) => $record->icon);

In Blade

@php
    $html = rescue(fn () => svg($record->icon, 'h-6 w-6')->toHtml(), '');
@endphp

@if (filled($html))
    {!! $html !!}
@endif

Normalizing legacy Font Awesome values

If you have existing database values saved as fa-solid-* / fa-regular-* / fa-brands-*, normalize them to fas-* / far-* / fab-* when reading/writing:

use FawazIwalewa\FilamentIconPicker\Services\IconService;
use Illuminate\Database\Eloquent\Casts\Attribute;

protected function icon(): Attribute
{
    return Attribute::make(
        get: fn (?string $value): ?string => IconService::normalizeIconName($value),
        set: fn (?string $value): ?string => IconService::normalizeIconName($value),
    );
}

How it works

• The dropdown UI is Alpine.js.
• Icons are fetched lazily from a paginated JSON endpoint.
• The endpoint is protected by web + auth middleware and throttled.

Artisan commands

php artisan filament-icon-picker:list

Filter by set key:

php artisan filament-icon-picker:list --set=heroicons

Search:

php artisan filament-icon-picker:list --search=user

Export:

php artisan filament-icon-picker:list --json > icons.json

Testing

php artisan test

Changelog

See CHANGELOG.

Contributing

See CONTRIBUTING.

Security

See SECURITY.

License

The MIT License (MIT). Please see License File for more information.