Statamic Blade Icons Laravel Package

Getting Started

derteaser/statamic-blade-icons is a thin bridge between Statamic and blade-ui-kit/blade-icons — it lets you render SVG icon sets (Heroicons, Phosphor, Tabler, Font Awesome, custom sets) inside Antlers templates and the Control Panel without hand-rolling inline SVG.

Minimal setup:

composer require derteaser/statamic-blade-icons
# plus at least one icon set, e.g.
composer require blade-ui-kit/blade-heroicons

Then publish/inspect the addon config if you need to restrict or register sets:

php artisan vendor:publish --tag=statamic-blade-icons-config

Look first at:

1. config/statamic-blade-icons.php (or the package's config/ folder) — this is where sets are declared/cached.
2. The package README's tag/component handle — this is the single most important thing to confirm, since the template syntax is what you'll type hundreds of times.
3. config/blade-icons.php from the underlying blade-icons package if you need custom set paths.

First use case: drop an icon into an existing Antlers template (nav, footer, feature grid) and confirm it renders server-side, then reuse the same icon name in a Blade partial for a Vue/Livewire component so designers and developers reference one canonical name. If you're upgrading from v0.7, your first task is verifying what replaced the CP icon picker (see Gotchas) before touching templates.

Implementation Patterns

Antlers-first rendering. The addon's whole value is that content-editable templates can carry icons without a Blade file. Wrap the tag in a small partial for the repetitive cases:

{{ partial:components/icon name="heroicon-o-check" class="w-5 h-5 text-green-600" }}

Blade side-by-side. In Blade views, prefer the native component syntax (<x-heroicon-o-check class="w-5 h-5" />) — it's compiled and cached by Laravel, and it keeps the same icon naming convention as the Antlers tag. Don't build a second abstraction layer on top; the underlying package is already the abstraction.

Set selection as a config concern, not a template concern. Install only the sets you use. Every set you composer require adds manifest scanning work and bloats the icon cache. For a multi-site build, keep the set list in config so a deploy is composer install + php artisan icons:cache, not a code edit.

Icon + content modelling. The common real-world pattern is an icon stored as a field value (a plain text/select field holding the icon name) and rendered in the template. This survives the v0.8.0 picker removal untouched — which is now the recommended approach. Keep the name in content, resolve it in the template.

Caching in CI. Add php artisan icons:cache to your deploy script (after config:cache). blade-icons caches discovered icons; without it, large sets pay a filesystem scan per request in production.

Composable with buttons/links. Build an "icon button" component once — icon name, label, href, variant — and let both Antlers and Blade call into it, so the accessibility markup (aria-hidden on decorative icons, visible label on interactive ones) lives in one place.

Gotchas and Tips

v0.8.0 removed the custom icon picker — treat this as the migration item. If any blueprint in your project references the addon's fieldtype for picking icons, that field will no longer resolve in the CP after upgrading. Migration path: switch the field to Statamic's built-in icon/select field, or a plain text field with a documented set of allowed names, and validate against your configured sets. Audit with a grep over resources/blueprints/ and resources/fieldsets/ before deploying. Pin "derteaser/statamic-blade-icons": "0.7.*" if you can't migrate immediately.

Dependency bump = verify the constraint matrix. v0.8.0 raised its dependency floor. Check the resolved blade-icons, illuminate/*, and Statamic versions against your PHP version, and re-run php artisan icons:cache after upgrading — a stale manifest from the previous blade-icons version is the most common source of "icon renders blank locally, works in CI" bugs. Clear with php artisan icons:clear then re-cache.

Icon names are namespaced and case-sensitive. heroicon-o-check vs heroicon-s-check vs a custom set's prefix — a typo produces silent empty output, not an exception. When an icon "disappears," check the rendered HTML for an empty <svg> or a missing node before you debug anything else, and confirm the set package is actually installed (the icon name existing in vendor docs is not proof).

Class merging and sizing. Passing class through the tag vs through Blade components can behave differently for the width/height/fill attributes. If icons render at the wrong size, inspect the final <svg> attributes; you may need to force sizing in your wrapper CSS rather than via attributes.

Don't render icons in loops without thought. A 100-row table with per-row icons is 100 SVG inlines. For icon-heavy UIs, consider an SVG sprite (<use href="#...">) or cache the rendered markup — the addon is convenience, not a sprite system.

Extension point: custom sets. If you have house icons, register a set (via blade-icons' config/icons path) rather than inlining SVGs by hand — that keeps the naming consistent with the addon's tag and means a future picker re-introduction or a select field can enumerate them.

Version pinning in multi-developer repos. Given the 0.x version line and the pace of maintenance releases, commit composer.lock and treat addon upgrades as a deliberate PR with a visual check of a few CP pages and one front-end template — the failures here are cosmetic and slip through unit tests.