Download the PHP package syriable/filament-icon-hub without Composer

Filament Icon Hub

A lightweight, extensible icon picker and icon provider system for Filament 5.

This single line gives you a searchable, paginated, keyboard-accessible icon picker covering every Blade Icons set installed in your application. Advanced applications can add local SVG directories, uploaded icons, or any remote icon API through a small provider contract, without the picker knowing where icons come from.

Contents

1. Requirements
2. Installation
3. Basic usage
4. Blade Icons
5. Local SVG provider
6. Custom providers
7. Remote API providers
8. Provider registration
9. Search
10. Filtering
11. Caching
12. Customization
13. Rendering
14. Icon library (uploads and hidden icons)
15. Security
16. Creating a provider: checklist
17. Configuration reference
18. Troubleshooting
19. Testing

Requirements

Installation

filament:assets publishes the picker's small JavaScript and CSS files. Run it again after every update of the package. It is usually part of your composer.json post-autoload-dump scripts already.

Optionally publish the config and translations:

You do not need to register a plugin to use the field, column, or entry. IconHubPlugin is only needed for the optional icon library screens.

Basic usage

Form field

What gets stored

Icons from Blade Icons sets are stored by their Blade Icons name, so the value works directly anywhere Blade Icons or Filament accepts an icon:

Icons that have no Blade Icons name are stored as a namespaced {provider}:{name} identifier: local SVG directories, the uploaded library, and remote or custom providers.

Both formats are always accepted when reading values. Older values such as heroicons:o-user still render and validate, and a form converts them to heroicon-o-user when it loads. To store namespaced ids for Blade Icons too, set blade_icons.store_as to id. A string column of 255 characters is enough for either format.

IconPicker behaves like any Filament field: required(), disabled(), hidden(), live(), helperText(), hint(), default(), afterStateUpdated(), validation, dehydration, and so on.

Multiple selection stores an array, so cast the attribute to array:

Select input (compact alternative)

IconSelect is Filament's native searchable Select whose dropdown shows the icons as a grid of tiles. The selected icon is shown with its name in the field. Use it when a modal is more than you need, for example in dense forms, filters, or table actions.

• It stores the same provider:name identifiers as IconPicker and uses the same registry, validation, and hidden-icon rules, so the two fields are interchangeable.
• Icons load when the dropdown opens and as you type. Nothing is fetched when the form renders, apart from the label of the selected icon.
• In the grid, names appear as tooltips and remain available to screen readers. Variants that share a name are labeled, for example Star (Outline) and Star (Solid). With grid(false) the dropdown is a list of rows with icon, name, and variant.
• Every Select option still works: required(), multiple(), placeholder(), searchDebounce(), live(), and so on.

Table column and infolist entry

Anywhere Filament accepts an icon

IconHub::html() returns an Htmlable, which every Filament ->icon() method accepts:

Blade Icons

Every registered Blade Icons set is discovered automatically and becomes a provider whose ID is the set name:

Install an icon package and it appears in the picker. Limit what is offered globally in config/icon-hub.php:

Or limit it per field:

Icons in subdirectories of a set (Blade Icons names such as solid.user) automatically get the directory as their category.

Local SVG provider

Point a provider at a directory of SVG files:

• Nested folders become categories and are part of the name.
• The directory is scanned once and the index is cached. Clear it after adding files with php artisan icon-hub:clear brand.
• File contents are sanitized on render, and the sanitized result is cached per file and modification time.

Custom providers

A provider implements one small interface:

Providers never render HTML. They return normalized Icon objects whose IconSource says where the artwork comes from:

When you can list every icon: extend IndexedIconProvider

This covers a JSON manifest, a design-system package, or a database table of a few thousand rows. You only build the list. Caching, search, ranking, pagination, categories, and variants are handled for you.

Anything else: implement IconProvider directly

You are responsible for search() pagination (IconQuery::$page, ::$perPage, ::offset()) and for caching expensive work through Syriable\Filament\Plugins\IconHub\Cache\IconCache.

Remote API providers

The core ships no Flaticon, Font Awesome API, or other service-specific code. Remote APIs extend the generic HttpIconProvider, which handles everything that is not specific to one API:

• connect and request timeouts
• 401/403 mapped to unauthorized, 429 to rate limited (with a Retry-After cool-down so the API is not hammered), 5xx to unavailable
• malformed JSON and mapping errors mapped to invalid response
• search result caching per query (provider + search + category + variant + page + per page)
• priming the icon cache from search results, so rendering an icon that was picked earlier normally never calls the API

Here is a complete example for a Flaticon-style API:

Register it and it shows up in every picker:

Failure behavior

When a remote provider fails (timeout, HTTP error, bad credentials, rate limit, malformed data), the picker shows a short provider-specific notice and every other provider keeps working. The form never breaks. Raw exception messages are logged through report() and never sent to the browser.

Provider registration

There are three equivalent ways to register a provider:

Other registry operations:

A provider registered with an existing ID replaces the previous one. This lets you override a discovered provider.

Search

Search runs on the server. The browser only ever receives the current page of icons (60 by default), each with pre-rendered, sanitized markup.

• Indexed providers (Blade Icons, local, custom indexed) match every search term against the name, label, tags, and category. Exact matches rank first, then prefix matches, then the rest.
• The library provider searches with indexed database queries.
• Remote providers pass the query to the API.

Search programmatically:

With several providers, results are served provider by provider, and the cursor remembers where the previous page stopped.

Filtering

The picker builds its filters from the registered providers. Nothing is hard-coded.

• Icon set: shown when a picker offers more than one provider. Providers that are not configured are listed but disabled.
• Style (variant): shown when the selected provider exposes variants (ProviderMetadata::$variants).
• Category: shown when the selected provider exposes categories (ProviderMetadata::$categories).

Caching

Cache keys are deterministic and include the provider and every query parameter (search, category, variant, page, per page), so a search for user can never return the results for home. Invalidation bumps a generation counter and works with every cache store, including those without tags:

In code, call app(IconCache::class)->flush('heroicons').

Customization

Arbitrary attributes

Pass any attributes (class, style, data-*, aria-*, x-*, @click, :class) to each rendered element:

Each method accepts a closure and a merge: true argument, like Filament's own extra*Attributes() methods.

Messages and translations

All labels and empty states (No icons found, No icons in this collection, Provider unavailable, No providers configured) live in lang/vendor/icon-hub/{locale}/icon-hub.php after publishing the translations.

Styling

The UI uses Filament's own components and color variables, so it follows your panel's theme, dark mode, and RTL automatically. Hook your own CSS into the fi-icon-hub-* classes. For example, to change the grid density:

Rendering

• Unknown or unavailable icons render an empty string.
• Icons are decorative (aria-hidden="true") unless you pass aria-label, in which case they get role="img".
• Blade Icons render inline SVG, so currentColor and CSS sizing work. Remote URL icons render as <img> and cannot be recolored with CSS.

Rendering never calls a remote API for icons that were selected through the picker: search results prime the icon cache, and lookups are also memoized per process. Table columns therefore stay cheap.

Icon library (uploads and hidden icons)

The optional library lets administrators:

Icons that are already stored keep rendering after being hidden or disabled, so existing data never breaks.

1. Enable it:

2. Publish and run the migration (two tables: icon_hub_icons and icon_hub_hidden_icons):

3. Register the management screens on a panel:

The Icon library resource manages uploads. The Hidden icons resource lists hidden icons and offers a Hide icons action that opens a multiple icon picker.

Hide icons statically without a database:

Or programmatically:

Authorization: the resources follow Filament's normal policy resolution. Create ManagedIconPolicy and HiddenIconPolicy (or register policies for your own models configured in library.models) to restrict who may upload and hide icons.

Security

Creating a provider: checklist

• [ ] id() is lowercase (a-z, 0-9, ., _, -) and never changes: it is stored in your database.
• [ ] label() and status() do no network I/O.
• [ ] search() honors page and perPage, and sets hasMore correctly.
• [ ] find() resolves every name that search() returns.
• [ ] Icons are returned with the provider's own ID in Icon::$provider.
• [ ] Anything expensive is cached through IconCache, or you extend IndexedIconProvider or HttpIconProvider, which do it for you.
• [ ] Throw exceptions freely. The registry isolates them. Throw ProviderException::timeout(), ::unauthorized(), and so on to show a specific message.
• [ ] Add match default arms when switching on SourceKind. New kinds may appear in minor releases.

Configuration reference

Troubleshooting

The picker button does nothing, or the modal is empty and unstyled. Run php artisan filament:assets. The picker's JavaScript and CSS are Filament assets.

My new SVG files or icon package do not appear. The index is cached. Run php artisan icon-hub:clear, or icon-hub:clear {provider}.

A provider shows "(unavailable)" in the filter. Its status() is not Available. For remote providers, isConfigured() usually returned false (for example, a missing API key).

"The icon service did not respond in time." The remote API timed out. Other providers still work. Increase $timeout on your provider, or check the logs: every provider failure is reported through report().

A stored icon renders nothing. The provider was removed or renamed, the icon no longer exists in the source, or the provider is not available. Provider IDs are part of stored values, so never rename them. Register the old ID again if needed.

Validation says the icon is invalid. The value must be provider:name, the provider must be allowed on that field (->providers([...])), and the icon must exist.

Remote icons are black and cannot be recolored. URL sources render as <img>. Return IconSource::svg($markup) from your provider if the API offers SVG markup. It will be sanitized.

Testing

Architecture

See docs/ARCHITECTURE.md for the package structure, provider architecture, data model, rendering and caching strategies, Filament integration, security considerations, and decision records.

License

MIT. See LICENSE.md.