Icons Laravel Package

Product Decisions This Supports

Feature & design-system decisions

• Theming/white-labeling: lets each brand or tenant ship its own SVG set and render it as <x-icon-brand-logo /> without code branches. Directly enables multi-brand theming, per-client agency deliverables, and white-label SKUs.
• Premium icon sets: the Font Awesome Pro use case is the sharpest one — teams that paid for Pro icons get a legal, low-friction path to using them (BYO SVG files) instead of bundling a webfont. This is as much a licensing/compliance decision as a technical one, and the v2 redesign (dropping bundled FA assets) materially reduces redistribution risk.
• Cross-package icon contribution: if your product is a platform with first- or third-party add-on packages, this is the seam that lets an add-on register its own icon set without the host app knowing about it. That's a real architectural decision (extensible vs. closed icon system), not just a convenience.
• Icon-agnostic UI layer: decouples your UI components from "we use Font Awesome" or "we use Heroicons." Swapping icon libraries becomes a config change rather than a refactor — useful if you expect to re-skin or re-theme on a roadmap horizon.

Build vs. buy

• The honest framing: the package is a thin wrapper over blade-ui-kit/blade-icons (a config array + a filter hook). A capable engineer could reproduce the core in under a day. So the buy case is not "we can't build this" — it's "we don't want to own an icon registry." Value is in convention, documentation, and the cross-package hook contract.
• Buy if you're already inside the artisanpack-ui ecosystem (hooks, visual editor, livewire-ui-components) and want the shared convention. Build/vendor-inline if you're outside it — you'd otherwise take a dependency on artisanpack-ui/hooks just to get a config loader.

Roadmap implications

• Treat icon registration as separate from icon supply. Registration is cheap and stable; supply (which sets you ship, who maintains them, licensing) is the ongoing cost. Budget for the latter, not the former.
• If a roadmap item is "let customers/partners extend our UI," this package is a plausible reference pattern even if you don't adopt the dependency — the event-hook registry design is worth copying.

Use cases where it fits cleanly: Laravel 12/13 SaaS with a brand design system; agencies shipping per-client icon sets from one codebase; package vendors who need their icons available in host apps; teams standardizing on inline SVG over icon webfonts.

When to Consider This Package

Adopt when most of these hold:

• Stack is Laravel 12.x/13.x, PHP 8.2+ (8.3+ for L13) and you already use or will use blade-ui-kit/blade-icons — this package is additive on top of it, not a replacement.
• You have ≥2 icon sources (e.g., a brand set plus a premium set), or you expect to.
• You need programmatic registration from other packages — the ap.icons.registerIconSets filter is the actual product here.
• You're already in the artisanpack-ui family (hooks, visual editor, livewire-ui-components) and the shared hook naming convention has value to you.
• You want inline SVG components (<x-icon-fa-home class="..." />) with Tailwind-friendly class passthrough, and you want to stop shipping icon webfonts.

Look elsewhere — or build it yourself — when any of these hold:

• Single icon set, single app. A config/blade-icons.php entry is one line. This package adds a dependency to save you that line; not worth it.
• Dependency-risk tolerance is low. 0 stars, 0 dependents, one maintainer ecosystem, and a history of breaking changes: v2.0 deleted a 17k-line Icons class, removed helpers, facades, Blade directives, and asset routes; v2.1 swapped tormjens/eventy for artisanpack-ui/hooks with a syntax change; v2.2 renamed the hook and kept only a deprecation alias slated for removal in the next major. That's three breaking-ish moves across three minors/majors in a short window. If you can't absorb that cadence, pin hard or skip.
• You need non-Blade rendering — Vue/React/JS-side icon usage, icon fonts, or CSS class workflows. This is deliberately Blade-component-only.
• You want a large, battle-tested community. There is effectively no external user base to lean on for bug discovery.
• You need offline/air-gapped determinism over convenience — you'll be fetching and curating SVGs yourself regardless; the package only registers them.

Adoption guardrails if you proceed:

• Pin the exact minor version and read changelogs before bumping; treat this as infrastructure.
• Wrap it. Reference icons through your own Blade component or a small internal helper rather than sprinkling <x-icon-...> and addFilter() calls everywhere, so a swap or a hook rename is a one-file change.
• Demand a regression test in your app that renders one icon from each registration path (config and event). The 2.1.2 bug — addSet() dropping the prefix, which made Factory::add() throw and broke every <x-...> render in the host app — is the exact failure mode to guard against. Silent breakage of every Blade component is a severity-1 incident for a one-line omission.
• Legal review the icon supply. The package is MIT, but Font Awesome Pro SVGs are not; self-hosting is better than bundling but still governed by your FA license terms.

How to Pitch It (Stakeholders)

For executives — one paragraph: ArtisanPack UI Icons is a small, MIT-licensed Laravel add-on that lets us register our own SVG icon sets and use them as Blade components, instead of hardcoding an icon library into the app. The business case is design-system portability and licensing hygiene: teams can swap icon libraries by config, ship per-brand icon sets for white-label customers, and legally self-host paid sets like Font Awesome Pro without bundling webfonts into our codebase. Cost is near zero and the integration surface is thin. The offsetting risk is vendor maturity — the package has no meaningful adoption, a single-ecosystem maintainer, and a track record of breaking API changes across recent releases, including one regression that broke all Blade component rendering for affected apps. Recommendation: run a short spike, pin the version, wrap it behind our own abstraction, and do not make it a load-bearing dependency unless we're already committed to the ArtisanPack UI package family.

For engineering — the ask:

• ~1–2 day spike: register two sets (one config-based, one event-based), render one icon from each in a test, confirm it plays nicely with any existing blade-icons / owenvoke/blade-fontawesome usage.
• Abstraction: own a thin internal component/helper; no raw addFilter('ap.icons.registerIconSets', ...) calls scattered through packages. The hook was renamed once already with the old name on a removal clock.
• Version pin + changelog gate on every bump; add a render smoke test that covers both registration paths.
• Fallback plan: the core is a config array plus a registry hook — if the dependency becomes painful, we can vendor ~100 lines and keep our abstraction intact.