Statamic Heroicons Laravel Package

Product Decisions This Supports

• Build vs. buy for the icon layer: This package owns Heroicons rendering (variants, wildcard/camel-case names, Blade-friendly parameters) so the team doesn't maintain its own SVG partial library, sprite pipeline, or variant-mapping logic. v3.3 is a maintenance-only upgrade — no new API surface — which keeps that "buy" decision cheap to sustain.
• Framework upgrade sequencing: Statamic 6 support plus CI coverage on Laravel 12 and PHP 8.2–8.5 removes a hard blocker from the platform upgrade roadmap. If a Statamic 6 / Laravel 12 migration is planned, this release is the version that unblocks it.
• Security posture for CMS-authored content: Hardened rendering when variant/icon input is invalid, plus escaping of double quotes in SVG attribute values, reduces XSS surface where icon names or variants can be influenced by editors or user input. Worth citing in a security review of any Statamic-driven site.
• Developer ergonomics / support-load reduction: Preserved case-insensitive icon parameters and camel-case wildcard names mean existing templates keep working and fewer "icon not rendering" bugs land on the team. Relevant to estimates for design-system rollouts and to onboarding cost.
• Feature scoping: Signals that icon selection is a first-class concern in Statamic content modeling — supports decisions about whether editors pick icons via CMS fields versus hardcoded templates.

When to Consider This Package

• Adopt when: You're on Laravel 11/12 and/or Statamic 5/6, need Heroicons specifically, and want Blade-level rendering without a JS build step for icons. Upgrade is a minor-version bump — low risk, no migration work expected.
• Adopt as the enabling version when: You're planning Statamic 6 or Laravel 12 and the current pin blocks it. This release is the compatibility gate.
• Look elsewhere when: You need a broad multi-set icon library (Font Awesome, Material, custom in-house sets) or runtime icon uploads — evaluate a more general icon or asset package instead.
• Look elsewhere when: Front-end performance budgets demand build-time tree-shaking and inlined SVGs; a PHP-rendered icon component adds per-request work versus compiled assets.
• Check before adopting: PHP floor (CI covers 8.2–8.5, so treat 8.2 as the minimum), accessibility defaults (aria attributes, titles), and whether Statamic editor-facing icon fieldtypes are in scope or come from a separate addon.
• Re-evaluate if: You're still on Statamic 4 or Laravel 10 — confirm the supported matrix before pinning, since this release targets the newer stack.

How to Pitch It (Stakeholders)

For executives: This is a low-risk minor upgrade to a small dependency that renders our icons. It adds support for the newest Statamic and Laravel versions, so it clears the path for our planned platform upgrade, and it tightens how icon markup is escaped — a modest but real security improvement for content edited in the CMS. There is no migration work, no change to how our templates call it, and it reduces the amount of icon plumbing we maintain ourselves. Recommended: take the upgrade in the next maintenance window.

For engineering: v3.3 is additive and backwards compatible. Statamic 6 support with CI across Laravel 12 and PHP 8.2–8.5 gives us a tested compatibility claim rather than a hopeful one. Existing case-insensitive icon parameters and camel-case wildcard names are explicitly preserved, so current templates should not regress. Rendering is hardened against malformed variant/icon input and double quotes in SVG attribute values are now escaped — worth a quick check anywhere icon names are editor- or user-supplied. Action: bump the constraint, run the existing view/component tests, and spot-check icon output in a Statamic 6 branch.