Download the PHP package erickcomp/laravel-lazy-blade-icons without Composer

laravel-lazy-blade-icons

Component-like tag syntax for blade-icons, with defer, fallbacks and runtime icon names — without registering every icon as a Blade component on every request.

Why this exists

blade-icons offers three ways to render an icon, and each one makes you give something up:

Two of those rows deserve an explanation.

Registration. BladeUI\Icons\Factory::registerComponents() walks the whole icon manifest and calls Blade::component() once per icon, for every set — on every request that renders any view, no matter how many icons the page actually uses. php artisan icons:cache removes the filesystem scan, not the registration loop. blade-icons acknowledges the problem itself: components.disabled exists, in its own words, "to avoid performance problems when working with large icon libraries" — but turning it on costs you the tag syntax entirely.

Defer. Svg::deferContent() returns a string containing literal Blade directives (@once, @push). Those are only ever compiled on one path: a class-based Blade component, whose returned string Laravel writes to storage/framework/views and renders as a real view. That is why the blade-icons README warns that deferring "doesn't work with the @svg Blade directive or the svg() helper function" — and why this package reimplements deferring against the view factory directly, instead of forwarding the attribute.

The upshot is that this package occupies a spot none of the native syntaxes do: short tags, deferring, fallbacks and runtime names, at no fixed per-request cost.

Requirements

• PHP 8.3+
• Laravel 12.60+ or 13.10+
• blade-icons 1.10+

Installation

The service provider is auto-discovered. Publish the config if you want to change anything:

Usage

Static icons

The icon name is the tag suffix — the same name you would pass to @svg():

Every attribute lands on the <svg> element, and the set's and the global default classes apply, exactly as with the native syntaxes. title produces a <title> element with role="img", same as blade-icons.

Runtime icon names

Use the reserved dynamic suffix. The name can come from the is attribute:

…or from the tag content, which is handy when the name is assembled or chosen by control flow:

The content is template text, so the name goes in as plain text — no echo, no quotes. Surrounding whitespace is trimmed.

Giving the name both ways throws, as does giving it neither. Content or an is attribute on a tag that already names its icon (<x-icon:fas-camera>…) throws too — the error messages say which is which.

dynamic is a reserved suffix. Icons in a set are always prefixed (fas-, heroicon-…), so a real icon can't collide with it; if you somehow have one, rename the keyword with the dynamic_keyword config option.

Deferring

When the same icon appears many times on a page, defer emits it once as a sprite and references it everywhere else:

The sprites are pushed to the bladeicons stack, so your layout needs it near the bottom:

Without that stack, deferred icons render nothing — they become <use> elements pointing at an id that was never emitted.

This is the same stack, the same id scheme and the same hash as blade-icons' own defer, so the two interoperate: <x-icon:fas-camera defer /> and <x-fas-camera defer /> on the same page share a single sprite.

Pin an id when you want to reference the icon from JavaScript:

Deferring everything

Set defer in the config to stop repeating the attribute:

A string in the config namespaces the generated ids; a string on a tag pins that one icon's id. Two different icons can therefore never collide on a shared id.

Fallback icons

blade-icons' fallback options work here, including the per-set one — which the native per-icon component syntax cannot do, because Blade fails to resolve the unknown component before the icon factory is ever consulted.

Configuration

Benchmark

Measured with 9 icon sets installed (24,991 icons: Font Awesome, Heroicons, Bootstrap Icons, Lucide, Tabler, Phosphor), PHP 8.4, Laravel 13, Xdebug off, medians of 7 runs. Reproduce with composer install -d benchmarks && php benchmarks/run.php.

What every request pays before a single icon is rendered:

This package pays none of it.

Rendering:

Total per request, 250 icons on the page:

Deferring 250 copies of one icon takes the HTML from 254.4 KB to 44.9 KB, in 6.26 ms against 18.16 ms for the native component.

Limitations

• No IDE support for the tags. They never reach Blade's component registry, so editor plugins that understand blade-icons — Laravel Idea in particular — won't autocomplete or navigate them.
• Tag matching is its own regex. It comes from erickcomp/laravel-raw-blade-components and parallels Blade's own component-tag grammar rather than reusing it, so exotic edge cases may diverge.
• @verbatim does not protect these tags. A native component inside @verbatim is left alone; one of these tags is still rewritten, so @verbatim<x-icon:fas-camera />@endverbatim renders the icon instead of printing the tag. The rewrite runs in Blade's prepareStringsForCompilationUsing pass, which happens before the pass that shields verbatim blocks. It only bites when you are documenting the syntax inside a Blade view; use <x-icon:…> or a plain string there.
• Deferring reads blade-icons' output. It post-processes the markup Svg::toHtml() returns; an upstream change to that format would need a matching change here. Two tests guard the boundary: one asserts the sprite id matches the native component's, the other asserts the upstream defer markup still carries uncompiled directives.
• No slots or @props. Icons don't need them, but don't expect this to generalise into a component system.

How it works

The package registers a single prefixed raw component through erickcomp/laravel-raw-blade-components, which rewrites the tags during Blade's prepareStringsForCompilationUsing pass — before the component compiler ever sees them. The compiled template calls IconRenderer, which asks BladeUI\Icons\Factory for the SVG and, when deferring, pushes the sprite through the view factory's own stack and once-tracking. There is no component class, no alias registration and no per-icon compiled view.

Testing

License

MIT.