Blade Line Awesome Icons Laravel Package

Getting Started

Install (one command, nothing else required):

composer require codeat3/blade-line-awesome-icons

Package auto-discovery registers the service provider and the icon set. There is no npm/Vite step, no CSS link, no font files, no publish step. Defaults are usable immediately.

Render your first icon in any Blade view:

<x-line-awesome-user />

That is the whole day-one experience. Component names come from the shipped SVG filenames, and Line Awesome's naming is a near 1:1 map of Font Awesome's la-* classes — so your existing knowledge transfers directly:

Mechanically: strip la-, prefix with x-line-awesome-.

Where to look first, in order:

1. The SVG directory — vendor/codeat3/blade-line-awesome-icons/resources/svg/. This is the authoritative list of what you can render. ls | grep user beats guessing names, and it settles the "does this glyph exist?" question in one second.
2. vendor/codeat3/blade-ui-kit/blade-icons (the transitive dependency). This is where behavior actually lives — attribute handling, caching, the @svg directive, default classes. Read its README before you read this one twice.
3. The package config — php artisan vendor:publish with no arguments, then pick the blade-line-awesome-icons :config tag. Two keys matter: the icon path and the component prefix. Default prefix is line-awesome; change it here if it collides.
4. The upstream Line Awesome reference for visual browsing — the vendor directory is fine for names, but you want to see glyphs before picking them.

First use case to convert: an authenticated app shell — sidebar/top-nav items and icon-only action buttons in a table. High visibility, internal-only audience, low conversion risk, and it exercises the two patterns you'll reuse everywhere (icon + label, icon-only button with an accessible name). Prove the pattern there before touching marketing pages.

Implementation Patterns

Attributes pass straight through to the <svg>

Everything on the component lands on the root SVG element, so Tailwind sizing and semantic attributes work as expected:

<x-line-awesome-bell class="w-5 h-5 text-gray-500" />

<x-line-awesome-check-circle
    class="w-6 h-6 text-green-600"
    aria-hidden="true" />

<x-line-awesome-cog class="w-4 h-4 animate-spin" />

Always decide decorative vs. semantic

This is the one convention worth writing down on day one, because retrofitting it across hundreds of call sites is miserable.

{{-- Decorative: adjacent text already carries the meaning --}}
<button>
    <x-line-awesome-save class="w-4 h-4" aria-hidden="true" />
    Save
</button>

{{-- Semantic: icon-only, the icon IS the label --}}
<button type="button" aria-label="Delete record">
    <x-line-awesome-trash class="w-4 h-4" aria-hidden="true" />
</button>

Rule of thumb: aria-hidden="true" on essentially every icon, and put the accessible name on the interactive parent (aria-label or visually-hidden text), not on the SVG. Only reach for role="img" + a <title> when the icon is standalone content that a screen reader must announce.

Wrap it once, use it everywhere

Do not scatter raw <x-line-awesome-*> tags across 200 templates. Create a single project component that owns sizing, color, and the a11y default:

{{-- resources/views/components/ui/icon.blade.php --}}
@props([
    'name',
    'size' => 'w-5 h-5',
    'decorative' => true,
])

<x-dynamic-component
    :component="'line-awesome-' . $name"
    {{ $attributes->class([$size]) }}
    aria-hidden="{{ $decorative ? 'true' : 'false' }}"
/>

Then call sites are stable and swappable:

<x-ui.icon name="user" />
<x-ui.icon name="trash" class="text-red-600" />

This is your migration escape hatch too — if you later replace Line Awesome with Heroicons or an in-house set, you change one file, not the codebase.

Dynamic icon names (nav configs, DB-driven menus)

{{-- Component syntax --}}
<x-dynamic-component :component="'line-awesome-' . $item->icon" />

{{-- Directive syntax (from blade-ui-kit/blade-icons) --}}
@svg('line-awesome-' . $item->icon, 'w-5 h-5 text-slate-400')

{{-- Helper, useful outside views --}}
{!! svg('line-awesome-check', 'w-4 h-4')->toHtml() !!}

A common pattern: keep the icon name in a config/PHP array and never let a user-supplied string reach the component name (see Gotchas).

Icons in loops and tables

@foreach ($actions as $action)
    <a href="{{ $action['url'] }}" class="inline-flex items-center gap-2">
        <x-ui.icon :name="$action['icon']" size="w-4 h-4" />
        {{ $action['label'] }}
    </a>
@endforeach

Icon-dense tables are exactly where the render cache matters most — see the deploy step below.

Cache the icon manifest in every deploy

Uncached, each icon resolves a file from disk under vendor/. That's fine for a footer, not for a 50-row data table with three icons per row.

php artisan icons:cache

Treat this as a required deploy step alongside config:cache and view:cache, not a later optimization ticket. On multi-node or read-only container filesystems, run it during the image build (or a release step) so every node has the manifest. Verify it in staging — a read-only filesystem plus a cache command that wants to write is an avoidable outage.

Local development: php artisan icons:clear after you add or publish icons.

Publishing icons (only if you need to)

You can publish the SVG set into resources/svg/ to subset it, patch fills, or add glyphs the vendor set lacks:

php artisan vendor:publish   # then choose the blade-line-awesome-icons :icons tag

Understand what you're taking on: the published copy is now yours, it will not update on composer update, and it drifts from the package. Publish only if you have a concrete need (see the fill/stroke note in Gotchas).

Testing call sites

Icons are presentation, so don't assert on markup you don't own. Do assert that a page renders and that dynamic names resolve:

$response = $this->actingAs($user)->get('/dashboard');
$response->assertOk();
$response->assertSee('aria-hidden="true"', false);

A cheap smoke test that catches the single most common production failure — an icon name that doesn't exist — is a loop over every icon name in your nav config:

it('resolves every configured nav icon', function () {
    foreach (config('navigation.items') as $item) {
        expect(svg('line-awesome-' . $item['icon'])->toHtml())->not->toBeEmpty();
    }
});

Gotchas and Tips

An unknown icon name throws, it does not fail gracefully. blade-ui-kit/blade-icons raises BladeUI\Icons\Exceptions\SvgNotFound. In a hardcoded template that's a loud, obvious error — good. In a dynamic name derived from a database column or user input, it's a 500 on a page that used to work. Always sanitize dynamic names against a whitelist:

$icon = in_array($item->icon, config('icons.allowed'), true) ? $item->icon : 'question-mark';

Sizing surprises: the icon has no intrinsic size. Inline SVGs without width/height default to the CSS box, which is often enormous. Two fixes: pass a class with Tailwind sizing every time (hence the wrapper component above), or set a global default in the blade-ui-kit/blade-icons config:

// config/blade-icons.php
'class' => 'w-5 h-5',   // merged with any class you pass on the component

Note that the config file belongs to the transitive dependency, not this package — publish blade-icons:config, not the icon-set config.

currentColor is not guaranteed for a filled/stroked path. Line Awesome SVGs come from a webfont-derived set; some carry hardcoded fill or stroke values that ignore text-* classes. If class="text-red-600" does nothing, open one SVG in vendor/.../resources/svg/ and check. Fixes, cheapest first: pass fill="currentColor" on the component (attributes pass through and win), or publish the set and normalize the attributes in a one-off script. Verify this on one icon before you build a color-coded status system on top of it.

Component-name collisions fail hard. Blade component names are global. A short or generic prefix will collide with your own components (<x-icon>, <x-user>), and the failure mode is a confusing "unable to locate component" or a silently wrong render. line-awesome- is reasonably safe; if you shorten it via the config prefix, audit your resources/views/components/ tree first.

Name-resolution rules trip people up. Nested directories in the SVG set map to dots, not slashes or hyphens. If a glyph doesn't resolve, check the actual filename — case, hyphens, and numbering (arrow-left-1 vs arrow-left) differ from what the webfont class list implied. When in doubt, ls the vendor directory.

Rebuild the cache after every change that touches icons. New deploy, config change, published-icon edit, composer update — all invalidate the manifest. A stale cache manifests as old glyphs or missing icons that definitely exist on disk, which sends people debugging the wrong layer for an hour. First debugging step is always:

php artisan icons:clear && php artisan icons:cache && php artisan view:clear

In production, the equivalent is "did the deploy actually run icons:cache?" — check the release script before you check the template.

Watch the transitive version, not this one. Actual rendering behavior lives in blade-ui-kit/blade-icons. It is the likelier source of breakage than a bump to this package, whose releases are mostly "new icon set snapshot" or framework-constraint chores. Pin a known-good pair in composer.lock, and when you upgrade this package, look at what blade-icons resolved to in the same operation.

On the Laravel 13 bump (1.6.0): the changelog is a single line. Before merging, check composer.json on the tag to determine whether the framework constraint was widened (supports 12 and 13) or raised (drops 12). A raised floor is breaking and invisible in the changelog text. Note also that README version claims lag well behind actual composer.json constraints — trust the manifest, not the docs.

Email and PDF renderers are a separate project. Inline SVG is unsupported in Gmail and Outlook desktop. If your mail templates use <i class="la la-*"> today, converting them to Blade components will produce broken mail for a chunk of recipients. Keep a webfont or PNG fallback for email; do not assume the Blade component translates.

Upstream Line Awesome is effectively frozen. The SVGs are static and safe to ship, but do not assume new glyph coverage and expect brand/logo marks to drift from current logos. If someone asks for a logo that "looks old," that's the answer — and it's a design-system decision, not a bug. Record it as an intentional interim choice.

CSS built around the webfont doesn't carry over. Anything selecting on i.la, sizing via font-size, or using ::before pseudo-element glyphs is now dead code. When you convert a surface, sweep the CSS with it — otherwise you're maintaining rules that match nothing and will quietly be "fixed" by someone later.

Pin and lockfile. Single maintainer, four stars, MIT, no SLA. That's fine for a bundled icon set with a thin wrapper — but composer.lock committed and exact versions pinned is the whole mitigation. The fallback (publish the SVGs, drop the package, keep the components) is genuinely cheap here, which is precisely why the risk is acceptable.

Keep the old webfont live for one release cycle. During migration, run both mechanisms in parallel and roll surface-by-surface: internal admin → authenticated app shell → public marketing. Rollback is then "restore the CSS link and revert the template," not "revert a release."