Filament Icon Picker Laravel Package

Technical Evaluation

Architecture fit

• Presentation-layer only: the package contributes one Filament form field (Guava\IconPicker\Forms\Components\IconPicker) and one table column (Guava\IconPicker\Tables\Columns\IconColumn). It introduces no models, migrations, or persistence of its own — the stored value is a single icon identifier string on your existing table. That keeps blast radius small and makes the package trivially removable.
• It sits on top of blade-icons as the icon registry, so the "domain" of selectable icons is whatever icon sets are installed in the app. Heroicons ship by default with Filament, so the field is useful with zero additional icon dependencies.
• Only relevant to teams running Filament panels. For a Laravel app without Filament, or a Filament app with no user-configurable icon surface, there is no architectural justification — skip it.
• The value proposition is real for admin UX: letting non-developers choose navigation icons, model "badges," or frontend-rendered icons without a code deploy.

Integration feasibility

• Standard Composer install (composer require guava/filament-icon-picker) plus php artisan filament:assets. Package is on Packagist, MIT licensed, with a changelog and tagged releases.
• Two non-obvious setup requirements create most of the integration friction:
  1. A custom Filament theme is mandatory — the package's CSS is not part of Filament's default build. Without one, the picker renders unstyled.
  2. A @source '../../../../vendor/guava/filament-icon-picker/resources/**/*'; line must be added to theme.css so Tailwind scans the package's views. This is a build-pipeline change, not a code change, and it's the step most likely to be missed and to fail silently in production.
• The package auto-registers two HTTP endpoints (/_icon-picker/index and /_icon-picker/svgs) secured by an encrypted per-field token. This is a meaningful architectural decision: icon delivery moved out of Livewire into normal HTTP requests. It's better for performance and caching, but it means the package now owns URL namespace and request surface inside your app.
• Optional config publish (--tag=filament-icon-picker-config) exposes route prefix, middleware, and cache settings — the escape hatch for anything the defaults get wrong.

Technical risk

• Low-to-moderate overall, but with specific sharp edges:
  • Route surface: a hardcoded _icon-picker prefix on a globally registered route group. Needs verification against existing route names, WAF/CDN rules, and any middleware that assumes authenticated-only paths.
  • SVG upload is an attack surface. The package supports users uploading their own icons and added SVG sanitization and label restrictions in 5.0.0 — the fact that sanitization was added as a feature rather than shipped from day one should inform how much you trust it. Treat uploaded SVGs as untrusted content and decide deliberately whether to enable that capability.
  • Token model: encrypted per-field tokens authorize icon listing. Failure modes are opaque to end users (empty library), so instrument it.
  • Churn across majors: the compatibility matrix spans Filament 2→5, and 5.0.0 is a substantial breaking release (uFuzzy replaces fuse.js, JS getter methods removed, cache config namespace moved from icon-picker.cache.* to filament-icon-picker.cache.*, CanBeCacheable removed, icon labels changed, getIcon() now returns null for missing files). Expect to pay an upgrade tax with each Filament major.
  • Ecosystem signal is weak: 0 dependents and no star count is a real signal. You are an early adopter. That is not disqualifying for a small, MIT-licensed, easily forkable package, but it means you cannot rely on community bug triage.

Key questions

1. Which Filament major are we on, and therefore which plugin major (2.x→Filament 3, 3.x→Filament 4, 4.x/5.x→Filament 5)? Are we prepared to upgrade the plugin in lockstep with Filament?
2. Do we have (or are we willing to own) a custom Filament theme with a Tailwind build step? Who owns that pipeline when it breaks?
3. Do we need user-uploaded custom icons, or is a curated set of pre-installed blade-icons kits sufficient? Default to the latter unless there's a product requirement.
4. What middleware should the _icon-picker routes carry — web, auth, panel middleware — and does our WAF allow the prefix?
5. Is icon selection per-tenant or per-scope? The package supports scopes and allowed-set restrictions; confirm the scoping model matches our tenancy model.
6. What is our exit plan if the package is abandoned? (Likely cheap: values are plain strings, and the package is small enough to vendor or fork.)
7. What is the expected icon-set size, and have we sized the payload/caching accordingly?

Integration Approach

Stack fit

• Laravel + Filament admin panels, Composer/Packagist distribution, Blade + Alpine + Livewire internals, Tailwind for styling. It slots in with no adaptation layer — this is a native Filament plugin, not an adapter around a generic library.
• Requires a non-default build posture (custom theme + @source directive). Teams already running a custom Filament theme will absorb this in minutes; teams on the stock theme will need to stand one up first, which is the real cost.

Migration path

• Greenfield usage is a two-line change in a form schema and a table definition, plus a nullable string column.
• For apps currently storing icon names in a free-text field or an enum, migration is a data-shape no-op — the package reads and writes strings. The mapping work is validating that existing stored identifiers resolve against your installed icon sets, and backfilling a fallback for values that don't.
• Watch the v5 label change: display labels dropped the set prefix ("O academic cap" rather than "Heroicon o academic cap"). Confirm whether identifiers stored by older versions still resolve under 5.x before committing to an in-place upgrade; if not, plan a one-time data normalization pass rather than an in-place upgrade on production data.

Compatibility

• Pin the plugin major explicitly in composer.json and document the Filament-major mapping in the repo. Never let a composer update cross a Filament major and the plugin major simultaneously — that couples two unrelated risk surfaces.
• On Filament 5, prefer plugin 5.x over 4.x: both work, but 5.x carries the caching, route-based serving, and search-performance work. Choosing 4.x is buying a migration you'll do later anyway.

Sequencing

1. Spike (branch, ~half a day): install, publish assets, add the @source line, get one form field and one column rendering in a local panel. This surfaces the theme-pipeline risk immediately and cheaply.
2. CI/build change: ensure php artisan filament:assets runs in the deploy pipeline and that the Tailwind build includes the vendored package path. This is the most common production-only failure.
3. Config decision: publish config and set route prefix/middleware/cache deliberately rather than accepting defaults, and record why.
4. Staging validation: confirm the two endpoints resolve behind auth and WAF, confirm caching headers, confirm a missing-icon record renders a placeholder rather than a blank or an error.
5. Feature rollout: enable the picker on one low-risk resource (e.g., navigation icon customization), gather feedback, then widen.
6. Production: deploy with asset publish in the pipeline; add a smoke check that the picker renders.

Operational Impact

Maintenance

• Small code surface, single maintainer, MIT license, regular-ish releases. Effort is not in day-to-day upkeep but in Filament-major upgrades, where the plugin has a demonstrated history of breaking changes (5.0.0 removed public JS methods, renamed the cache config namespace, and changed null semantics). Budget this as a line item in every Filament upgrade plan, not as an afterthought.
• Because it's a Composer dependency pinned to a Filament major, dependency drift is bounded and predictable.

Support

• Documentation lives off-repo at guava.cz; the repo carries README, changelog, and releases. There is no SLA and effectively no community (0 dependents). Escalation path is: read the docs, read the changelog, inspect the source, then fork.
• Forkability is the real safety net — the package is small, MIT, and self-contained. Treat "we can vendor this in a day" as the support guarantee rather than assuming upstream responsiveness.

Scaling

• 5.0.0 is explicitly a performance release: server-side icon-listing cache, token-authorized routes replacing Livewire round-trips, uFuzzy replacing fuse.js, batched client-side SVG fetching, and single-icon resolution by direct file lookup instead of enumerating a set. That's the right architecture for a picker with hundreds-to-thousands of icons.
• The scaling question shifts to HTTP request volume against /_icon-picker/*. These are per-session, per-picker requests; without browser/CDN caching tuned via config they become a steady background load on the app tier. Size the icon sets and set cache TTLs intentionally.
• Client-side SVG fetching is batched, but a very large icon library still costs client memory and initial render time. Limit the exposed sets per field where possible.

Failure modes

• Missing icon file → getIcon() returns null and the column renders blank. Silent and user-visible. Use the column's placeholder support and monitor for nulls.
• Assets not published in deploy → broken or unstyled picker in production only. Add filament:assets to the release process and assert it.
• @source line missing from theme.css → unstyled picker; the Tailwind build silently excludes package classes.
• Route blocked or prefix colliding → empty icon library, with no obvious error to the user. Needs an alert.
• Encrypted token mismatch/expiry (e.g., after APP_KEY rotation) → icons fail to load. This is a non-obvious coupling worth documenting in the runbook alongside key-rotation procedures.
• SVG upload abuse → stored XSS via crafted SVG. Sanitization exists but the capability should be off unless product-justified.
• Icon set upgrade removes an identifier → records reference dead icons and render blank. Add a periodic integrity check if icon usage is widespread.

Ramp-up

• A mid-level Laravel/Filament developer can complete the code integration in well under a day. The genuine learning curve is the Tailwind/Filament theme pipeline, not the package API — the API is two static factory calls.
• Realistic onboarding estimate: 1–2 days end-to-end including the theme build change, CI/deploy pipeline update, config decisions, and a short internal runbook covering route/middleware, cache tuning, key rotation, and the upgrade-per-Filament-major policy.
• Because the feature is self-evidently demoable, product/stakeholder validation is fast — good candidate for a small spike-then-ship rather than a formal design review.