Filament Icon Select Column Laravel Package

Product Decisions This Supports

• Build-vs-buy on back-office UI, decided on cost-per-feature rather than strategic grounds. Any roadmap item where an operator picks or scans an icon on a record — navigation and menu builders, taxonomy and category management, status/type badges, CMS content types, dashboard widget config — can be satisfied by composing this column instead of commissioning a bespoke picker-plus-renderer. The comparison to run is "days of engineering saved per icon-bearing feature" against "one Composer line plus a version-watching obligation." It is a velocity lever for internal CRUD work, not a platform bet.
• Scope discipline: keep it off the customer roadmap. This is an admin-surface dependency with zero customer-facing exposure. It should never gate a customer release, appear in external narrative, or be framed internally as a differentiator. Calling it "internal delivery speed" keeps it out of prioritization fights it does not belong in.
• Sequencing the Filament v4 upgrade. The 3.x line targets Filament v4 exclusively; 2.x targets v3. The package version is therefore not an independent variable — it is derived from your Filament major. The PM decision is binary: "do the Filament v4 upgrade and this together in one branch," or "defer both." Adopting it on a v3 panel is not a small bet; it is a coupled migration disguised as a dependency add.
• Closing small polish tickets cheaply. The recurring complaint "the icon field is free text and people paste invalid names" collapses into a schema change. That recovers design and engineering capacity for work with actual customer impact — a straightforward capacity-reallocation decision.
• Accepting a bounded risk class deliberately, in writing. Adoption means accepting single-maintainer risk, no SLA, no security review artifacts, no accessibility conformance documentation, and a silent failure mode — a broken interaction renders wrong rather than throwing, so logs, error tracking, and CI will not catch it. The mitigation package (pin the version, smoke-test on every Filament bump, name an internal owner) is a policy decision worth making on purpose rather than by default.
• A worked example of dependency hygiene you can generalize. The 3.0.0 → 3.0.1 history — a full v4 rewrite that shipped without behavioral parity, patched only in 3.0.1 — is a reusable argument for grouped Filament-core-plus-plugins upgrade PRs, pinned version constraints, and behavior smoke tests around plugin rewrites. Useful precedent beyond this package.

When to Consider This Package

Consider it when:

• The product runs Filament v4 and the admin panel already depends on Filament's table stack. There is no standalone value outside that ecosystem, so it should never be adopted speculatively as a "we might need it later" line.
• The need is concrete and repeated: a column that both displays an icon and lets an operator select one, consistently across several resources, rather than three diverging bespoke implementations.
• The team prefers a pinned, versioned Composer dependency over owning and testing an in-house icon column — and accepts that the fallback is genuinely small (days), which is precisely what keeps the criticality low.
• The blast radius is acceptable: a regression here means an awkward admin interaction or a confused editor — not data loss, downtime, or a customer-visible defect.
• Someone can be named as internal owner for version watching, changelog review, and post-upgrade verification.

Look elsewhere — or build in-house — when:

• You are on Filament v3 or earlier, or not on Filament at all. Introducing 3.x ahead of a scheduled upgrade buys cross-major compatibility risk for no benefit.
• The icon interaction is core to the product experience (an end-user-facing icon or brand designer). A table column is not a design tool; buy the depth the feature actually requires.
• You need contractual assurances this package does not offer: support SLAs, security review evidence, accessibility documentation, or a maintainer bus factor above one.
• Your icon set is dynamic, remote-sourced, or governed by an asset pipeline the picker's options UX does not model — validate against the real icon provider before committing.
• You require proven adoption. The dependency graph is effectively empty and the project is young. That is not disqualifying for internal tooling, but it should govern how much you lean on it.

Release-specific read (3.0.1). This is a patch that restores closeOnSelection behavior lost in the Filament v4 rewrite. Two PM-relevant facts. It is a fix, not a breaking change — no migration, safe on a routine bump. And it is a maturity signal: 3.0.0 was a full rewrite for v4 that shipped with a silent behavioral regression in a user-facing interaction. Treat 3.0.0 as unusable, enter at 3.0.1, pin ~3.0.1 rather than ^3.0, and verify behavior on each Filament upgrade instead of trusting semver.

Questions to answer before committing: what Filament constraint does 3.0.x actually declare, and which 4.x minors are exercised in CI; is there a published 2.x → 3.x upgrade guide or is the rewrite's parity-gap list undisclosed; is the closeOnSelection API shape unchanged from 2.x; how many other Filament v4 plugins does the panel depend on and do they have v4-compatible releases — that aggregate, not this package, is what usually stalls an upgrade.

How to Pitch It (Stakeholders)

To executives, in one line: a small, free, open-source component that saves engineering a few days of custom admin-UI work per icon-related feature, with risk confined to internal back-office screens and no customer-facing exposure.

To engineering leadership: Filament v4 already gives us forms and tables; this fills one narrow gap — an icon column that is both a display and a picker — so we stop writing and rewriting the same bespoke column across resources. It is a leaf dependency on an internal-only surface: no data model impact, no migrations, no queues, no scheduled work, no outbound calls, no environment variables, no runtime criticality, no scaling cost. Integration is one Composer line plus a column registration; reversal cost is deleting that line and reverting one schema call. The fallback — a custom Filament column — is genuinely days of work, which is exactly what keeps this low-criticality and the decision reversible.

To the delivery team: target 3.0.1 directly and pin ~3.0.1. If we are still on Filament v3, the Filament v4 upgrade and this package's 2.x → 3.x upgrade are one coupled change in one branch — upgrading either alone will strand the other. Rebuild Filament assets, because v4 changed the asset pipeline and a stale build can convincingly mimic a column bug. Group Filament core and Filament plugins into a single dependency PR so coupled upgrades get reviewed together, and exercise the restored behavior explicitly: selection closes the dropdown, in both modal and full-page table contexts, including keyboard navigation.

Caveats to state plainly: single maintainer; no formal support, security, or accessibility posture; zero dependents, so no downstream evidence of production hardening; and the 3.0.0 → 3.0.1 history shows the v4 rewrite introduced a regression that only a patch repaired. The failure mode is silent — nothing in logs, CI, or error tracking would have flagged it, and it surfaces as operator confusion or a support ticket.

Mitigations to commit to now: pin ~3.0.1 so patches flow but minors gate behind review; review changelogs on every bump; add one smoke test covering selection-closes-the-dropdown in both table contexts including keyboard navigation; and record the pinned version plus the coupled-upgrade rule in a short internal note so the next engineer does not repeat the 3.0.0 assumption of rewrite parity.

Recommendation: adopt for internal Filament v4 admin panels where an icon-selection column is actually needed. Do not adopt speculatively, do not adopt ahead of the Filament v4 upgrade, and do not let it become a dependency of anything customer-facing.