Blade Icon Picker Laravel Package

Product Decisions This Supports

• Build vs. buy for icon-selection UI. Every admin surface that lets users pick an icon — navigation/menu builders, category and tag iconography, CMS block settings, dashboard widget config, notification templates — needs the same picker. This package replaces a hand-rolled modal or a raw text field of icon names with a dependency-free component, at the cost of one Composer require instead of ~1–3 days of internal build plus ongoing maintenance.
• Unblocks icon-driven roadmap features. Any feature spec that says "choose an icon" (menu items, saved views, workspace branding, product categories) currently gets de-scoped or degraded to a plain text input. This makes the good version cheap enough to schedule.
• Low-regret data decision. The persisted value is a native blade-icons ID (e.g. heroicon-o-home), the same convention used by @svg(), Filament, and most Laravel admin tooling. That means adopting or later removing the picker is a UI change, not a data migration — which lowers the cost of saying yes now and re-evaluating later.
• Standardization decision. Today, icon selection is ad hoc per team/feature. Adopting one component (behind an internal wrapper) is a consistency and design-system decision as much as a technical one, and it is cheap to reverse.
• Scoping signal for "polish" work. Search, keyboard navigation, responsive grid, and dark-mode variables come free. That converts a "nice to have" backlog item into a near-zero-cost add for any form that needs it.
• Not a platform bet. Nothing here supports pricing, growth, or infrastructure decisions. It is a small, tactical UX dependency — treat it as such in prioritization (a chore/enabler, not a roadmap theme).

When to Consider This Package

Adopt when all of the following hold:

• The app is Laravel 10–12 + Livewire 3 (the Alpine island and $wire.set() contract are the whole integration surface).
• The team is already using, or willing to add, a blade-icons pack (Heroicons is the recommended default). No pack installed = a helpful error message, not a working picker.
• The picker lives in internal/admin-facing forms, where a few hundred KB of embedded icon catalog and an unverified accessibility story are tolerable.
• No Tailwind requirement matters to you — e.g. an admin panel sitting outside the main design system. This is a genuine plus.
• Asset publishing and two manual <link>/<script> tags are acceptable in your deploy pipeline.
• You're comfortable owning the dependency: zero stars, zero dependents, single maintainer, one recent release. Pin the version, commit the published assets, keep a fork-ready note.

Look elsewhere (or defer) when:

• The front end is Vue / React / Inertia, or the form layer is Livewire 2. The Alpine coupling becomes dead weight.
• Your CSP forbids inline SVG / unsafe-inline, or you need confirmed ARIA combobox/listbox semantics and screen-reader testing on a public-facing surface. Accessibility is claimed but unevidenced.
• You have multiple large icon packs installed and no way to allow-list them — the full catalog is serialized into every page hosting a picker, with no documented caching or build-time JSON generation.
• You need a vendor SLA, support policy, or release cadence. There is none.
• Page weight on the host screen is already a concern, or the picker would appear on high-traffic pages.

If none of the "look elsewhere" conditions apply, this is a credible low-regret adoption — but validate it with a half-day spike before committing, not after.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, MIT-licensed open-source component that gives our Livewire admin forms a proper icon picker — searchable, keyboard-friendly, responsive, no design-system dependency. It replaces a hand-rolled UI we would otherwise build and maintain, and because it stores a standard blade-icons ID, we can swap it out later without touching data. The risk is vendor risk, not technical risk: a single maintainer with no community usage behind it. We cap that by pinning a version, wrapping it in an internal component, and budgeting a small allowance to own a fork if needed. Recommendation: approve a one-day spike on one admin screen; the decision gate is page-weight and render-cost acceptability.

For engineering (the short version):

• What it is: a standalone Blade component that ships an Alpine island — not a Livewire component. Server renders every installed blade-icons glyph to inline SVG and serializes the catalog as JSON; the browser owns search, lazy chunking (30 at a time), and keyboard nav. Only server round-trip is $wire.set() on selection.
• Install: composer require, tagged asset publish, two manual tags. No service provider config, migrations, queues, or external services. JS auto-registers with Alpine in Livewire 3.
• The footgun: wire:model alone will not seed the initial value — :value="$icon" is mandatory. Validation and error display are entirely ours. Wrap the vendor tag in <x-app.icon-field> that enforces both bindings, error rendering, and theme binding, so no product developer calls it directly.
• What we must verify in the spike: measured JSON payload and server render delta for our packs; behavior on two pickers per page (catalog duplication?); graceful handling of a stale/unregistered :value; CSP compatibility with inline SVG; actual keyboard and screen-reader behavior; and the dark-mode contract — the README contradicts itself (ip-dark class vs [data-theme], and conflicting statements on prefers-color-scheme auto-detection), so resolve it empirically.
• Ask before we commit: can the catalog be cached per-deployment or pre-generated as a static asset, and is that on the maintainer's roadmap? If not, what is our workaround cost?
• Contingency: pin the exact version, commit published assets so deploys don't depend on re-publishing, and record a fork decision point. The surface area is small enough that one developer can own a fork.
• Sequencing: spike (½–1 day) → decision gate → internal wrapper → one low-traffic admin screen for a sprint → batch rollout with a PR-checklist rule for the dual-binding pattern.