Ux Icons Laravel Package

Product Decisions This Supports

• Design-system consolidation (build vs. buy). Decides whether icon delivery lives in a maintained package or in our own SVG sprite/pipeline. ux_icon() plus the <twig:ux:icon /> component gives a single, policy-enforceable entry point for every icon in a Twig template — which is what lets a design system team actually govern icons (prefixes, aliases, icon sets) rather than hope engineers copy the right <svg>.
• Where icons are rendered: server vs. client. This is an architectural fork, not a cosmetic one. Server-side inlining avoids an icon-font payload, avoids a CDN round-trip, and makes the icon part of the HTML response — which is the right call for above-the-fold chrome, emails, and print/export surfaces, and the wrong call for a heavily client-rendered SPA shell.
• Third-party dependency exposure. Remote Iconify fetching is opt-in but materially changes our risk profile: an external host becomes part of the render path unless icons are locked into the repo. The iconify.auto_lock option (3.4.0) and the "lock your icons" guidance are the knobs a PM should treat as the default, not an optimization — this is a "do we accept a runtime vendor dependency for a decorative asset?" decision with a clear answer.
• Upgrade-gate sequencing on the roadmap. v3 requires Symfony 7.4 and PHP 8.4. That is a platform commitment, not a package decision. If the org is mid-migration, adopting v3 pulls the PHP/Symfony upgrade forward on the roadmap; staying on v2.x is viable (2.36.1 carries the security fix) but starts a maintenance-debt clock. A PM should explicitly choose which of those two timelines they are buying.
• Security sign-off as a launch gate. CVE-2026-55877 (SVG XSS via Iconify bodies and local files) was fixed in 3.2.0 / 2.36.1, and the fix requires a cache clear because previously cached icons must be re-sanitized. This makes "which version, and did we purge the icon cache" a release-checklist item, not a background detail — directly analogous to any templating/escaping decision we already gate on.
• Performance budget ownership. 3.6.0 added rendered-HTML caching, one cache fetch per icon per request, and cache:warmup integration for local icons. That converts icon rendering from an unbounded per-template cost into something that behaves like config/route/view cache: predictable, warm at deploy, and safe to put in a perf budget. It also means icon-dense layouts (nav bars, data tables, status badges) stop being a per-page-cost argument in design reviews.
• Frontend/backend ownership boundary. Icons become a backend concern with a PHP API. That is a real org decision: it removes icon work from the frontend queue (good for throughput), but it also means frontend cannot ship a new icon without a template change or a config entry.
• Licensing and attribution. Because icon packs are pulled by name from Iconify, "which pack" is a licensing decision (per-pack licenses vary) that PM owns alongside legal — the package makes it easy to pull a pack, which makes it easy to pull one we shouldn't.

When to Consider This Package

Adopt when:

• The application is Twig-first (Symfony, or a Laravel app that has deliberately adopted Twig via a bridge). This is the dominant criterion — the package's entire surface is a Twig function and a Twig component.
• Icons are numerous and static (roughly 20+ across templates) and currently maintained by copy-paste. That is the point where a package beats a convention.
• Icons must be decided server-side — permission-gated, A/B-tested, localized, or themed per tenant — where a JS icon library would require shipping logic to the client.
• You want no icon font, no CDN, no JS runtime. Inline SVG with currentColor composes cleanly with Tailwind/Bootstrap utilities (class passes straight through to the <svg>).
• Your deploy pipeline already runs cache warmup (or you're willing to add it). 3.6.0's warmup hook is where a meaningful share of the value now sits.
• You can commit to the v3 floor (Symfony 7.4 / PHP 8.4) — or you have a credible plan to stay on 2.36.x with the security patch and revisit.

Look elsewhere when:

• Laravel/Blade-only stack with no appetite for Twig. This is the honest blocker. Bolting Twig onto a Blade codebase to gain an icon helper is a poor trade; established Blade icon packages and self-hosted SVG sprite tooling cover the same ground with zero template-engine risk. Do not let the "Laravel/PHP" framing in a package summary drive this call.
• Icons need motion or interactivity (animated loaders, hover choreography, Lottie-style vector animation). Inline static SVG plus CSS covers a lot, but not everything.
• You need PNG/WEBP fallbacks for legacy clients or email clients with poor SVG support.
• Hard no-egress policy combined with a team unwilling to maintain a locked local icon directory. Local-only operation is supported, but it becomes a curated-asset chore — someone has to own the folder.
• Your frontend is decoupled/static and icons are a build-time frontend concern. Server-side Twig rendering is the wrong layer.
• You need icon discovery, search, or user-selectable icon sets as a product feature — that's a different product (the Iconify browser itself), not a rendering helper.
• Serverless/frequent-cold-start deployments where warmup never happens. Runtime caches still help, but you're buying the package for the deploy-time guarantee and not getting it.

Signals worth weighing honestly: 56 stars and 0 dependents in this listing are misleading on their own — this is a read-only subtree split of the symfony/ux monorepo, so usage, issues, and PRs accumulate upstream. Score it on the parent project's health (Symfony-backed, MIT, active changelog with releases through 2026), not on this mirror's counters.

How to Pitch It (Stakeholders)

For executives: "We have a recurring, low-glory cost: every icon in every template is hand-carried SVG, which drifts from the design system, bloats review time, and occasionally ships something inconsistent. This package makes icons a one-line, server-rendered call — a single place to enforce which icons exist and how they look. It is MIT-licensed and maintained under the Symfony umbrella, so the downside is bounded. Since 3.6.0 it also caches rendered icon markup and pre-warms local icons at deploy, which turns icon rendering from 'hopefully cheap' into a number we can put in a performance budget. The cost is small: a version upgrade gate (PHP 8.4 / Symfony 7.4) and a short security checklist — we must be on the patched release line and clear the icon cache on deploy, because a recent SVG-XSS fix only applies to re-rendered icons. Biggest caveat, stated plainly: this is a Twig package. It fits us only if our templates are Twig; for a Blade-only codebase, the same outcome is available from Blade-native tooling and this is not the lever."

Key outcomes to headline: fewer hand-maintained SVGs, one governed icon vocabulary, no icon font or CDN in the critical path, and predictable render cost at deploy rather than at low traffic.

For engineering: "Narrow, well-scoped package: one Twig function and one Twig component that resolve an icon name to inline SVG, from a local directory or an Iconify pack, with class and other attributes forwarded to the <svg> and fill driven by currentColor. Practically, the things that matter for us:

• Lock the icons. Treat remote fetch as a build/deploy-time convenience, not a runtime behavior — use iconify.auto_lock (3.4.0) or a committed lock so production never depends on an external host and so template assertions stay stable. The 2.24.0 xmlns change is exactly the kind of output diff that silently breaks snapshot tests when icons aren't locked.
• Be on ≥ 3.2.0 (or ≥ 2.36.1). CVE-2026-55877 sanitized Iconify bodies and local files — script/foreignObject/iframe/embed, on* handlers, javascript:/data:text/html hrefs, SMIL targeting event or href attributes, and CDATA/PIs. <style> is retained for theming with breakouts stripped. Clear the icon cache after upgrading or you keep serving unsanitized cached markup.
• Wire warmup into the pipeline. Local icons warm on cache:warmup (3.6.0); repeated icons reuse cached rendered HTML, and each icon is fetched from cache once per request. Cold-start cost after a release drops to near zero and icon-dense pages stop scaling with icon count.
• Use the config surface instead of inventing one. aliases, icon_sets, prefixes, and suffixes (2.20.0 / 2.33.0) mean semantic names (icon:status-warning) can map to concrete icons — theme and rebrand become a config diff rather than a grep.
• ignore_not_found (2.19.0) to avoid a missing icon taking down a page render — decide deliberately whether a missing icon is a hard failure (dev/CI) or a silent gap (production).
• Known edges: v3 floor is Symfony 7.4 / PHP 8.4; SVG-only output; and the whole integration is Twig, so if we're on Blade this evaluation ends there and we should look at Blade-native equivalents."