Statamic Heroicons Laravel Package

Getting Started

This release (v3.3) is primarily a compatibility and hardening release: the addon now supports Statamic 6, is CI-tested against Laravel 12 on PHP 8.2–8.5, and fixes several edge cases in tag rendering. There are no deprecations or breaking changes called out, so an existing v3.x install should upgrade cleanly — you mainly gain Statamic 6 support and more forgiving rendering.

First steps:

1. composer require the addon (or composer update <vendor>/<package> if already installed), then verify the installed version is 3.3.
2. Confirm your runtime matrix: Statamic 6 requires Laravel 12 and PHP 8.2+. If you're still on Statamic 5, stay on the previous 3.x release until you've planned the Statamic 6 upgrade — check your other addons first, since Statamic 6 is the gating change, not this addon.
3. Clear caches after upgrading (php artisan optimize:clear, plus php artisan statamic:stache:clear if icon registration is cached in your setup).
4. Look first at the README's tag reference and the addon's config file. The two things you'll actually configure day-to-day are the default variant (outline/solid/mini/micro) and any default CSS classes applied to rendered SVGs.
5. First use case: drop a single Heroicon into an existing Antlers partial — typically a nav item, button, or card — and confirm it renders inline SVG you can size with Tailwind classes.

Implementation Patterns

Inline in Antlers partials. The dominant usage is rendering an icon directly in a template, passing the icon name and your utility classes. Keep the markup in a small reusable partial (e.g. partials/icon.antlers.html) that takes the name, variant, and class as parameters, so sizing and aria-hidden behaviour live in one place instead of being repeated across templates.

Dynamic icons from content. The common real-world pattern is an icon name stored in a field (a select, a Bard/Replicator set, or a dedicated icon fieldtype) and passed to the tag as a variable. Because v3.3 hardened rendering when the variant or icon input is missing, a field that's empty or unset now yields no output rather than an error — pair that with an {{ if }} guard when you need a fallback icon.

Wildcard and camel-case icon names. v3.3 preserves camel-case names when resolving wildcard-style tags. This matters for the handful of Heroicons whose names are genuinely camel-cased (e.g. arrowUpTray, arrowDownOnSquare). If you generate tag strings dynamically, don't run them through a strtolower() or slug helper — you'll silently break those icons.

Case-insensitive parameters. Parameter names are matched case-insensitively, so class and Class both work. Pick one convention (lowercase) and stick to it; mixed casing in a codebase is a readability trap, and third-party snippets copied from the docs may use a different case than your house style.

Blade-heavy projects. Where you're rendering through Blade rather than Antlers, keep the icon markup in a Blade component that wraps the addon's output, so both template engines share one sizing/aria convention. Avoid duplicating icon markup between the two.

Composition. Icons almost always sit inside a button, link, or input group. Set aria-hidden="true" on decorative icons via your shared partial, and use aria-label on the parent control. Pass those attributes through the tag rather than concatenating them into the SVG yourself.

Gotchas and Tips

• Missing icons fail silently now. The v3.3 hardening means a typo'd icon name or an omitted variant produces empty output instead of an exception. That's better for production, worse for debugging — when an icon "disappears," check the icon name and variant first, not your CSS.
• Variant-specific name sets. Heroicons don't have identical names across outline/solid/mini/micro. An icon that renders in outline may be absent in mini. Verify against the upstream Heroicons set for the exact variant you're requesting.
• Attribute escaping changed. v3.3 escapes double quotes in SVG attribute values. If you were passing pre-escaped or hand-built attribute strings, review them — you may now get double-escaped output. Prefer passing attributes to the tag and letting it handle escaping.
• Template and stache caching. After upgrading, stale compiled views can mask the fix you're trying to verify. Clear view cache and the Statamic stache before concluding something is broken.
• Inline SVG bloat in loops. Rendering an icon per row in a large listing inflates HTML significantly. For long tables or grids, consider a single sprite/<use> reference or caching the rendered fragment rather than repeating full SVG paths.
• Extension points worth knowing. Publish the addon's views/config if you need to change the wrapper markup or globally apply a default class; registering the default class once in config is far cleaner than passing the same Tailwind string to every tag invocation.
• Upgrade ordering. If you're moving to Statamic 6 at the same time, do the Statamic/Laravel/PHP bump in its own commit and confirm the site renders before layering other addon updates on top. The CI matrix in this release (Laravel 12, PHP 8.2–8.5) is a good description of the supported target — don't assume it on PHP 8.1 or Laravel 11.