Filament Icons Laravel Package

Product Decisions This Supports

• Build vs. buy for admin UX primitives: Icon selection and icon rendering are recurring "everyone hand-rolls it" problems in Filament panels. This package replaces a small but repeated build (picker UI, search, prefix/template handling, dark/light rendering, table column) with a Composer install. The decision it informs is whether to fund a shared internal UI primitive or accept a tactical OSS dependency — and the honest answer is that the build is only worth doing if icon taxonomy is a differentiated product surface.
• Feature scoping for icon-driven admin features: Enables (or de-scopes) features that depend on attaching a visual marker to a model — category/tag icons, navigation group icons, status indicators, menu builders, product line badges, dashboard shortcuts. When a roadmap item says "let admins pick an icon," this package turns that from a design-and-engineering ticket into a form-schema line.
• Consistency and brand governance across panels: Because the picker is a single component, product can set one icon vocabulary (Heroicons baseline, plus approved providers) rather than letting each squad ship its own free-text icon field. This supports a decision to standardize icon storage as a constrained value set with a defined default and fallback, which is a product-quality decision, not just a technical one.
• Admin UX investment sequencing: It supports the judgment that searchable, visual pickers are a convenience tier of admin UX — worth adopting where panels are numerous or admin-facing, deferrable where there is exactly one panel and one icon field.
• Roadmap gating on platform versions: Because package majors track Filament majors (v5 requires Filament ^5.0/Livewire 4/Laravel 12–13/PHP 8.3–8.4; Filament v4 panels must stay on the v4 branch), adoption is implicitly a decision to align admin panels to the current Filament upgrade train. That makes it a useful forcing function — or a reason to defer — in platform modernization planning.
• Make-vs-adapt for custom icon libraries: The provider facade (asset URL, template, prefix replacement, icon list) means product can approve additional icon sets without engineering rework, but each addition becomes a reviewed, committed provider plus a cache-refresh runbook step. This frames the decision as "who owns icon taxonomy and provider approval" rather than "which icons do we like."

When to Consider This Package

Adopt when:

• You run one or more Filament admin panels on Laravel 12/13, PHP 8.3/8.4, and can match the package branch to your Filament major (v5 → v5; Filament v4 → v4 branch).
• You have more than a couple of icon fields, or expect them to multiply (categories, statuses, menus, navigation), so the per-field saving compounds.
• Visual consistency in the admin matters — internal tools, back-office CRUD, multi-tenant admin where customers see icon-labeled navigation.
• You want a small, MIT-licensed, low-coupling dependency that lives entirely in the presentation layer and touches no domain, data, or API code.
• You can own the operational tail: filament-icons:install / filament-icons:clear sequenced into CI/CD and multi-node/blue-green deploys, plus a validation rule and fallback for stored icon values.

Look elsewhere or defer when:

• Your panels are on Filament v3 or older Laravel/PHP. The platform upgrade dwarfs the package's value; don't let a picker drive a framework migration.
• The need is a single icon field on a single panel — a static select of five Heroicons is cheaper than a dependency, a cache command, and a governance conversation.
• You need animated, bespoke SVG, or illustration workflows, or icons outside Filament's rendering model. This is a class-string picker, not a design-asset pipeline.
• You require vendor support, an SLA, or a security response commitment. At 39 stars, 0 reported dependents, and a likely single-maintainer profile, treat this as tactical OSS: pin the version, document the exit plan, and be prepared to fork.
• Custom templates or externally hosted CSS cannot pass security review or be self-hosted/vendored. Trusted-code inputs need sign-off per provider.
• Your deployment model can't guarantee cache warm-up — serverless/scale-to-zero, frequent rollbacks, or unmanaged multi-node fleets will produce blank or stale icons.

How to Pitch It (Stakeholders)

For executives — one paragraph: Filament Icons is a small, free (MIT) add-on for our admin panels that gives admins a searchable icon picker and lets tables display icons, instead of each team building that widget separately. It's a productivity and consistency play, not a platform bet: hours of integration, no data-model or API impact, and it can be removed without touching business logic. The trade-offs are real but bounded — the project has low community adoption, so we pin the version and keep a fork-or-replace contingency, and it must be upgraded in lockstep with Filament. Recommend piloting on one non-critical panel before deciding on wider rollout.

For engineering — the ask:

• Confirm Filament/Livewire/PHP/Laravel versions per panel and pick the matching package branch; do not mix branches across panels.
• Pilot in one panel: composer require tomatophp/filament-icons, run filament-icons:install, wire one IconPicker and one IconColumn. Publish config/views only if defaults fall short.
• Define the icon field contract before rollout: allowed provider values, a validation rule on write, a default icon, and a fallback render for deleted or renamed icons. Backfill any existing free-text icon columns.
• Register custom icon libraries only as reviewed provider code committed to the repo, with assets self-hosted or vendored; treat templates and asset URLs as trusted-code inputs requiring security sign-off.
• Add filament-icons:clear + filament-icons:install to the deploy pipeline and document the rollback sequence.
• Set an exit trigger (e.g., a Filament major with no matching release, an unresolved security concern, or a stalled-maintenance window) at which we fork or replace.

What success looks like: fewer bespoke picker implementations, one icon vocabulary across panels, and a repeatable "add an icon field" story measured in minutes — with no increase in the admin's failure modes (blank icons, broken renders) after deploys.