Weave Code
Filament Icon Picker Laravel Package
guava/filament-icon-picker
Filament Icon Picker adds an icon picker form field and matching table column to Filament panels. Choose from any installed blade-icons kit, Heroicons included by default—ideal for custom navigation, model, and frontend icons. Token-secured endpoints, configurable caching.
This Filament plugin adds a dedicated icon picker form field and matching table column, letting users choose from any blade-icons kit installed in your project—heroicons work out of the box since Filament ships them. It's handy for customizable navigation icons, small model icons for quick recognition, or any frontend icon your users should control.
- Any icon kit – supports all installed blade-icons sets
- Form field & table column – consistent picking and display
- Secure endpoints – icons served via encrypted per-field tokens
- Configurable – tweak caching, route prefix, and middleware
- Filament 5 ready – 4.x/5.x plugin versions, with performance gains in 5.x
Frequently asked questions about Filament Icon Picker
- What does the guava/filament-icon-picker package actually do?
- It adds a Filament form field (Guava\IconPicker\Forms\Components\IconPicker) and a matching table column for picking icons from any blade-icons kit installed in your app, with Heroicons available by default because Filament already ships them. Typical uses are user-customisable navigation icons, per-model icons for easy recognition in admin tables, or small visual identifiers in a resource form. It is purely a presentation-layer primitive that stores whatever string your own column expects, so it does not touch models, persistence or auth. Stewardship is effectively single-maintainer, so treat it as a convenience field rather than something worth deep customisation.
- How do I install filament-icon-picker in a Laravel app?
- Run composer require guava/filament-icon-picker, then publish the package assets with php artisan filament:assets. Next, make sure you have a compiled custom Filament theme and add the line @source '../../../../vendor/guava/filament-icon-picker/resources/**/*' to your theme.css. Rebuild the theme (npm run build) and the field should render correctly. Skipping the theme step is the most common reason the picker appears unstyled or icon-less.
- Which Filament versions are supported by filament-icon-picker?
- Compatibility is an explicit matrix: plugin 1.x targets Filament 2, 2.x targets Filament 3, 3.x targets Filament 4, and 4.x/5.x target Filament 5. Both 4.x and 5.x run on Filament 5, but 5.x is the recommended line because it contains server-side caching and batched SVG performance improvements. Check the version table before requiring the package so Composer does not pull a branch built for a different Filament major.
- Why is my Filament icon picker not showing any icons or missing styles?
- Almost always because the package CSS is not being compiled into your panel. The picker requires a custom Filament theme with the @source directive pointing at vendor/guava/filament-icon-picker/resources/**/* in theme.css, followed by a theme rebuild. Also confirm you ran php artisan filament:assets after installing. Budget this as a real task in your estimate rather than a one-line afterthought, especially on projects still using Filament's default non-compiled styling.
- Are user-uploaded SVG icons safe with this package?
- Version 5.0.0 added SVG sanitisation and label restrictions, but sanitisation is a mitigation, not a guarantee. User-supplied SVG is a stored-XSS vector by nature, so treat icon uploads as an opt-in feature that needs security sign-off rather than a default. If you only need the bundled Heroicons or other curated blade-icons sets, disabling uploads removes the highest-risk surface entirely.
- What are the /_icon-picker/index and /_icon-picker/svgs routes the package registers?
- The package auto-registers those two endpoints and secures them with an encrypted per-field token so the browser can fetch icon sets and SVG markup. They are still publicly reachable surfaces in your application, so they must be reviewed against your middleware stack, WAF, CSP rules and any proxy or caching layer. You can publish the config file to change the route prefix, middleware and caching behaviour. The token model is per-field, not per-tenant, so verify behaviour before assuming it fits a multi-tenant setup.
- What breaking changes did filament-icon-picker 5.0.0 introduce?
- Version 5.0.0 replaced Livewire-based icon serving with route-based serving and removed the getSetJs(), getIconsJs() and getIconSvgJs() methods. The config namespace moved from icon-picker.cache.* to filament-icon-picker.cache.*, the CanBeCacheable contract was deleted, and getIcon() now returns null for missing files. Any custom component subclass or code reading the old config keys will break loudly, so follow the upgrade guide before bumping. If you have no customisations, the upgrade is usually just Composer plus an asset republish and theme rebuild.
- How do I configure caching for the icon picker?
- Publish the package config file and adjust the keys under filament-icon-picker.cache.* (note the namespace changed in 5.0.0 from icon-picker.cache.*). Server-side caching is one of the main reasons the maintainer recommends the 5.x line, alongside batched SVG performance work. Pick a TTL that matches how often your icon sets change, and remember that adding a new blade-icons kit means the cached index needs to refresh.
- Can I use guava/filament-icon-picker outside Filament, or in an Inertia/Vue app?
- No. It is a Filament form field and table column, so it only delivers value inside a Filament 3, 4 or 5 admin panel. Headless or API-only backends, Inertia/Vue frontends without Filament, and panels relying on default styling with no compiled theme get nothing from it. If you need icon selection in a plain Blade or Livewire form, a simple select or a custom Blade component is a lighter alternative.
- What does the icon picker store in the database, and is it easy to remove later?
- It stores a plain string identifier that your own column defines, so decide deliberately whether that is a Blade icon name, a file path, or a foreign key to an icons table. Because the package never owns the persistence, adoption is incremental and reversible: add the dependency, publish assets, add the @source line, and roll it out on one low-traffic resource first. Choosing a stable data contract means the stored values survive a future move off the package, which matters given the zero-dependents, single-maintainer risk profile.
Weaver
How can I help you explore Laravel packages today?