Statamic Heroicons Laravel Package

Getting Started

• Install with composer require simonhamp/statamic-heroicons and (if prompted) publish the config: php artisan vendor:publish --tag="statamic-heroicons-config". There are no migrations or control-panel setup steps — this is a rendering addon, not a content-type addon.

• Look first at config/statamic-heroicons.php (default icon style, default CSS classes) and the addon README, which is the authoritative reference for the tag syntax. The source lives under vendor/simonhamp/statamic-heroicons/src if you need to confirm how a name is resolved.

• First use case: drop an icon into an existing Antlers view. In its simplest form the tag takes the icon name as the method/segment:

  {{ heroicon:academic-cap }}
  

  With an explicit style and classes:

  {{ heroicon icon="academic-cap" style="solid" class="w-5 h-5 text-gray-500" }}
  

  Confirm it renders inline <svg> in the page source before wiring it into layouts.

Implementation Patterns

• Treat the tag as an inline-SVG partial. Because the output is inline markup (not an <img> or sprite reference), it inherits currentColor and can be styled with utility classes. Pass class="..." rather than wrapping in extra divs, and keep sizing utilities (w-4 h-4, w-5 h-5, etc.) consistent across a project by putting them in the config default.
• Wrap in a Blade component for app-wide consistency. In Blade/Volt you can call the tag via Statamic::tag('heroicon')->params([...])->fetch(), or simply define a small <x-icon> Blade component that wraps the Antlers tag. This gives you one place to enforce aria-hidden="true", default classes, and a decorative-vs-meaningful switch.
• Drive icons from content fields. Store the icon name as a plain text/select field in a fieldset and interpolate it: {{ heroicon :icon="icon_field" }}. This is the common pattern for feature grids, navigation, and card components where editors choose an icon. Validate the stored value against the actual icon set on save if you want to avoid empty renders.
• Use it in sets and replicators where each block carries its own icon. Combine with class bound to a variable so list vs. detail views can size the same icon differently.
• Cache the markup if you render many icons. Inline SVG bloats HTML; for icon-heavy pages use {{ heroicon:... }} inside a {{ cache }} block or pre-render to a partial. For static sets of icons, consider generating a Blade partial of the SVGs once and @include-ing it.
• Pair with a design-token class convention. Keep stroke-width, size, and colour utilities in the config or component rather than scattering them across templates — Heroicons v2 ships distinct outline and solid variants, so make the style explicit per context (outline for navigation chrome, solid for active/selected states).

Gotchas and Tips

• v1.1.0 upgrades the underlying Heroicons set to v2 — audit your icon names. Heroicons v2 renamed and removed a number of icons (for example search→magnifying-glass, cog→cog-6-tooth, search-circle→magnifying-glass-circle, and several others were dropped entirely). The addon does not error on an unknown name; you typically get an empty or malformed SVG, which fails silently in production. Grep your templates and any stored field values for icon names and re-verify each one against the v2 list after upgrading.
• v2 also changed the default attributes on the SVGs (notably the aria-hidden/data-* attributes and, in the wider set, the size classes). If you were relying on a specific default class or viewBox, diff one rendered icon before and after the upgrade.
• Style/name parsing is string-based. Icon names containing hyphens (arrow-up-tray, chevron-double-left) are fine as the tag method, but mixing positional style and name can be ambiguous — prefer the explicit icon="..." and style="..." parameters in anything non-trivial to avoid surprises.
• Silent failures are the main debugging trap. If an icon doesn't appear, check (1) the name exists in the v2 set, (2) the style is valid for that icon (some icons exist only as outline or only as solid), and (3) the config default isn't overriding what you passed. Dump the raw tag output in a scratch template to isolate it.
• Accessibility is on you. Decorative icons should be aria-hidden="true" with no label; meaningful icons need an accessible name. The addon renders markup — it doesn't decide semantics. Bake this into your Blade wrapper so it isn't forgotten per-use.
• Performance: every tag render inlines a full <svg>. Hundreds of icons on a page is a real payload cost; cache or partial-ise as above, and don't use this addon as a sprite-sheet replacement for large icon grids.
• Extension points: publish and edit the config for defaults, and publish the addon views if you need to change the SVG wrapper markup (e.g. to inject focusable="false" or a consistent data-icon attribute). If you need a different icon library, the tag implementation is small enough to fork or wrap rather than fight the config.