Filament Icon Picker Laravel Package

Product Decisions This Supports

• Ship "user-customizable iconography" without building a picker. Any feature where an admin, tenant, or end user chooses an icon — navigation items, menu builders, category/badge markers, status iconography, dashboard widgets, notification types, CMS page templates — becomes a one-field configuration instead of a bespoke autocomplete + SVG-sprite + preview UI project.
• Roadmap sequencing: picker now, uploads later. The package covers both curated selection (from installed blade-icons kits like Heroicons) and user-uploaded custom icons. That lets you scope v1 as "choose from a curated set" and defer the messier "let users upload arbitrary SVGs" story to v2 without re-platforming the field.
• Build vs. buy: buy. The build alternative is roughly a searchable icon grid, per-field scoping, SVG serving/sanitization, client-side fuzzy search, server-side caching, and a table column for rendering. That is a multi-sprint front-end + backend effort for something that is an input control, not a differentiator. This is a clear commodity purchase at the cost of a Composer dependency.
• Multi-tenant and per-role customization. The scopes and allowed-set features are the product-relevant part: you can decide that Brand A's editors see only the brand kit, while internal admins see everything, and enforce it server-side rather than trusting the UI. That makes "custom icons" sellable as a tenant-level setting rather than a global toggle.
• Feature-flag / tier gating. Because icon sets can be limited per field, "premium icon packs" or "custom brand icons" become a plan-tier lever rather than a schema change.
• Prioritization signal on polish. The 5.0.0 release replacing client-side fuzzy search (fuse.js → uFuzzy), batching SVG fetches, moving icon delivery to token-authorized endpoints, and adding server-side listing caches tells you the maintainer is actively investing in perceived performance and access control — the two things that usually make icon pickers feel cheap in a demo.
• Deployment/ops decisions. Two new routes under /_icon-picker, a publishable config for prefix/middleware/cache, a required custom Filament theme with an @source directive, and a required filament:assets step. These are real onboarding costs that belong in your release checklist and installer docs, not surprises in QA.

When to Consider This Package

Consider it when all of the following hold:

• You are on Filament 3, 4, or 5 and the feature lives in a Filament panel. On Filament 5, take the 5.x line (the 4.x line also runs there but 5.x carries the performance work); on Filament 2 you would be pinned to 1.x — do not adopt on legacy Filament.
• The persona choosing the icon is an admin or operator, not an anonymous end user. This is a back-office input control.
• Icons are a decorative/identification concern, not a semantic one. If a wrong icon breaks a workflow, you need validation and preview coverage beyond what a picker gives you.
• You already ship (or are willing to ship) blade-icons and a custom Filament theme. The theme step is not optional, and skipping the @source line is the most common self-inflicted "styles don't load" bug.
• You can accept the 5.0.0 breaking changes if upgrading: config namespace moved to filament-icon-picker.cache.*, CanBeCacheable removed, getSetJs() / getIconsJs() / getIconSvgJs() removed in favor of the new routes, and getIcon() now returning null for missing files. Any custom code touching those APIs needs a migration ticket.

Look elsewhere or build deliberately when:

• You are not on Filament. This is panel-native; there is no meaningful reuse outside it.
• You need a fixed, tiny icon vocabulary (say, six status icons). A Select with hardcoded options is less surface area than a plugin, two routes, config, and a theme build step.
• User-uploaded SVGs are in scope and you have no sanitization story of your own. The package sanitizes uploads and restricts labels, which is good, but serving user-supplied SVG from your own domain is a security posture decision your team must own regardless of library.
• Adoption evidence matters to you. The package shows zero dependents and a single-maintainer credit line. That is not a reason to reject it — it is small, MIT, and readable — but it is a reason to budget for the possibility of forking it and to avoid spreading it across a dozen surfaces before it has proven itself in one.
• You need deep programmatic icon manipulation — resolving, transforming, or generating icon sets at scale. The plugin is an input control; treat its public API as UI-facing, not a domain service.

A reasonable adoption path: pilot on one surface (e.g., navigation item icons), pin the version, publish the config so route prefix and cache settings are under your control, and only then expand to tenant-level custom icon uploads.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can offer customers customizable iconography — their own brand icons, or a curated set on menus, categories, and dashboards — for roughly the cost of a Composer dependency rather than a development cycle. It is a mature, MIT-licensed, actively maintained plugin for our admin framework that handles the picker UI, search, secure icon delivery, and caching. The commercial angle is plan-tier differentiation: icon sets can be gated per customer without new engineering. The risk is low and bounded — small open-source package, single maintainer, easy to fork — and the main cost is a short setup step in our theme build, not ongoing maintenance.

For engineering: Drop-in Filament form field and table column (IconPicker::make('icon') / Guava\IconPicker\Tables\Columns\IconColumn). Works with any installed blade-icons kit, Heroicons by default. Requires filament:assets and an @source line in our custom theme CSS — put both in the installer runbook. The 5.x line is the one to take: it serves icons over two token-authorized endpoints under /_icon-picker instead of Livewire, caches icon listings server-side, batch-fetches SVGs, and replaces fuse.js with uFuzzy for search. Publish the config so we own the route prefix, middleware, and cache TTL. Note the 5.0.0 breaking changes (config namespace, removed getSetJs/getIconsJs/getIconSvgJs, getIcon() returning null) before any upgrade. We should pin the version, cover the upgrade path in our own changelog, and keep our usage behind our own wrapper component so a fork or replacement stays cheap.

For design/product ops: The field supports scoped, limited icon sets and user uploads with SVG sanitization, so we can expose "your brand icons" to tenants while keeping the default experience curated. Preview and search behave as a proper picker, not a raw dropdown.

Ask: Approve a one-surface pilot (navigation icons) with a version pin and a documented upgrade path; revisit a broader rollout — and premium icon packs as a paid tier — after one release cycle of real usage.