Blade Fontawesome Laravel Package

Getting Started

Confirm the floor before touching Composer. v3.x requires PHP 8.3+ and Laravel 12+. If the app is on PHP 8.2 or Laravel 11, you want 2.x (Font Awesome 6) or 1.x (Laravel ≤8) instead — the component syntax is the same, so this is a decision you make once and never think about again, but getting it wrong means a failed install or a surprise major upgrade later.

composer require owenvoke/blade-fontawesome

That's genuinely the whole install for the free sets. No service provider to register, no migration, no assets to build. Open any Blade view and drop an icon in:

<x-fas-cloud/>
<x-fab-laravel class="w-5 h-5 text-red-500"/>
<x-far-star style="color: #f59e0b"/>

Where to look first. The canonical icon-name reference for this package is resources/svg in the repo — one directory per set (solid/, regular/, brands/, …), one file per icon. The filename minus .svg is the component suffix. Once installed you can browse the same tree locally at vendor/owenvoke/blade-fontawesome/resources/svg, which is faster than the GitHub UI and lets you grep -r for an icon when you half-remember the name.

Publish the config on day one, not day thirty. Even if you don't set any defaults yet, you want the file in version control so sizing and colour rules are reviewable:

php artisan vendor:publish --tag=blade-fontawesome-config

Best first use case: replace existing font-based markup (<i class="fas fa-cloud"></i>) or hand-pasted SVG blobs in your layouts and partials. This is a mechanical, low-risk sweep — <i class="fas fa-cloud"></i> becomes <x-fas-cloud/> — and it immediately buys you three things: no Font Awesome CSS/webfont payload, no icon-font FOUT, and icons that inherit currentColor so text-gray-500 and dark-mode utilities just work. Do this in one PR across resources/views, then leave the config tuning for a follow-up.

The one config edit worth doing immediately is disabling Pro/Kit sets you don't have icons for. In v3.x every set in the config is loaded automatically; a Pro set left enabled without synced icons is a runtime exception waiting for the first developer who types <x-fal-star/>. If you're on the free tier:

// config/blade-fontawesome.php
'duotone' => false,
'light' => false,
'thin' => false,
'sharp-regular' => false,
'sharp-light' => false,
'sharp-solid' => false,
'sharp-thin' => false,
'sharp-duotone' => false,
'custom-icons' => false,

Implementation Patterns

Prefix map you'll memorise

All prefixes are configurable; the values in config/blade-fontawesome.php are the defaults.

Set defaults once, override per use

Because this wraps blade-ui-kit/blade-icons, the config exposes default classes and attributes that merge into every icon. Set an app-wide baseline and stop repeating Tailwind utilities:

// config/blade-fontawesome.php
'class' => 'inline-block w-5 h-5 shrink-0',
'attributes' => [
    'aria-hidden' => 'true',
],

Then a per-use class appends rather than replaces — <x-fas-cloud class="text-gray-400"/> renders with both the defaults and your override. This is the single highest-leverage piece of the package: it keeps icon sizing consistent across a large team without a wrapper component.

Wrap it in a semantic component

Once you have more than a handful of icons, stop calling <x-fas-*> directly in feature views. Icon choice is a design decision; feature views should express intent. A thin wrapper also gives you one place to change the underlying set later:

{{-- resources/views/components/ui/icon.blade.php --}}
@props(['name', 'set' => 'fas'])
<x-dynamic-component :component="$set . '-' . $name" {{ $attributes }} />

<x-ui.icon name="cloud" class="text-sky-500"/>
<x-ui.icon name="trash" set="far" class="text-red-600"/>

This is the idiomatic way to do dynamic icons in Blade and it keeps the prefix string out of forty call sites.

Pattern: icon buttons and alerts

Icons rarely live alone. Two compositions cover most of the day-to-day cases:

{{-- Icon-only button: label is required, not optional --}}
<button type="button"
        class="rounded p-2 text-gray-500 hover:bg-gray-100 hover:text-gray-700">
    <x-fas-cog class="w-5 h-5" aria-hidden="true"/>
    <span class="sr-only">Settings</span>
</button>

{{-- Status pill --}}
<span class="inline-flex items-center gap-1.5 rounded-full bg-green-50 px-2.5 py-1 text-xs font-medium text-green-700">
    <x-fas-circle-check class="w-3.5 h-3.5" aria-hidden="true"/>
    Active
</span>

Note the pattern: decorative icons get aria-hidden="true", meaningful ones get a text alternative. Never let a bare icon be the only accessible label.

Pattern: Pro icons, when you actually need them

Pro support is a two-stage workflow and it is not a Composer-only change — this is where most surprises happen:

npm i --save @fortawesome/fontawesome-pro
php artisan blade-fontawesome:sync-icons --pro

The command materialises SVGs into resources/icons/blade-fontawesome, and the package auto-detects that path. Decide deliberately whether that directory is committed (simplest, no npm in CI, but licensed assets in git) or generated in the build (needs an npm token for the private Pro package in CI). Teams usually pick "commit it" and put a comment in the repo explaining the licensing terms — you don't want a build pipeline that can't run without a credential nobody else has.

Kits work identically with an account identifier instead of a Pro subscription:

php artisan blade-fontawesome:sync-icons --kit=KIT_CODE

Pattern: raw SVGs for email and static assets

Inline SVG in HTML email is unreliable (Gmail and desktop Outlook both have problems with it). If you're rendering transactional email templates, publish the assets and use <img>:

php artisan vendor:publish --tag=blade-fontawesome --force

<img src="{{ asset('vendor/blade-fontawesome/solid/cloud.svg') }}" width="20" height="20" alt="">

Be aware of what this does: it publishes every set into public/vendor/blade-fontawesome/, which is hundreds of files. Treat it as a deliberate, one-time action for a specific need — not something to run casually during a refactor.

Cache on deploy if you're on Pro or Kit

This is the only performance knob that matters. Free icons are cheap; Pro/Kit icons incur a per-request filesystem scan across a much larger icon pool. Add the cache step to your deploy script:

php artisan icons:cache

It's a blade-icons command, and it belongs after blade-fontawesome:sync-icons in the pipeline, since the cache is built from whatever SVGs exist at that moment.

Livewire and Inertia

Blade Font Awesome is a server-rendered component. In Livewire it behaves exactly as in plain Blade and is a good fit for server-driven UI. In an Inertia/Vue/React app it delivers nothing — the components never render server-side, so use the @fortawesome/* npm packages there and skip this dependency entirely. Don't half-adopt it: pick one rendering path per surface.

Gotchas and Tips

An enabled-but-unsynced Pro set throws at render time, not silently. Because v3.x auto-loads every set present in the config, <x-fal-star/> without a Pro sync (or a Kit sync for fak) fails loudly rather than rendering nothing. Symptom is a "component not found" style error from Blade Icons on a page that was previously fine — usually after someone uncomments a set in the config. Fix: set the set to false and redeploy, or run the sync.

v3.0.0 inverted the set-loading semantics. If you're porting an older app: sets previously loaded only when explicitly configured; now everything in the config loads and you must opt out with false. The custom key also became custom-icons. Both are documented in UPGRADE.md; read it before bumping a major.

Pin patch versions and treat icon changes as visual regressions. Most releases are automated Font Awesome bumps (7.2.0 → 7.3.0 → 7.3.1) under a patch version, and Font Awesome 7 did rename and remove icons relative to 6. That means composer update can change glyphs or break a component name with no semver signal. Pin to a minor range:

"owenvoke/blade-fontawesome": "3.3.*"

…and when you do bump, diff the rendered output on a page that uses a spread of icons. It's a two-minute check that prevents a "the save icon looks different" bug report after a deploy.

Cache staleness is the classic debugging trap. If you add a Pro icon or run sync-icons and the icon still doesn't render (or renders the old glyph), your cached manifest is stale. php artisan icons:clear, then icons:cache again. In test suites, clear the icon cache in setup — otherwise a cached state from a previous run masks missing icons.

class vs :class both work, but be deliberate. Static class="w-5 h-5" gets appended to the config defaults. If you need conditional classes, :class with an array works; just don't assume class replaces — it merges.

Inline SVG has real byte cost. Each icon is a full <svg> block, roughly 0.5–1.5 KB depending on complexity. A table with a status icon per row × 100 rows is a meaningful HTML payload increase over a single cached webfont. If you're icon-dense, measure before and after; at extreme density the raw-asset <img> route (with long cache headers) is genuinely cheaper.

Use aria-hidden deliberately. The package's default attributes are a good baseline for decorative icons. For an icon that is the information (a lone status indicator, an icon-only button), you must add a text alternative — sr-only span or aria-label. This is the most common a11y miss with icon packages and it's cheap to get right if you handle it in the wrapper component.

Don't whitelist-bypass dynamic names from user input. <x-ui.icon :name="$request->input('icon')"/> lets a caller probe your icon namespace and, if the set is enabled, generate error pages. If icons are user-selectable, back the name with an enum or a validated allowlist.

Enums beat stringly-typed icon names. There's no autocomplete for Blade component names, so a Cloud icon referenced as fas-cloud in a dozen views is invisible to static analysis and to your IDE. A small PHP enum or a config/icons.php map of semantic names → icon names pays for itself the first time someone renames an icon and has to grep for it.

Bus factor of one — plan for it now, cheaply. Single maintainer, thin wrapper over blade-icons, MIT licensed. The exit cost is genuinely low (swap to blade-ui-kit/blade-icons + your own SVG directory, or fork), but name an internal owner and keep the config and any sync-icons steps documented in the repo. The failure mode isn't "the package breaks", it's "nobody remembers how the Pro sync works" — that's what the README in your own repo is for.

Treeware is a real, non-binding request. The license permits commercial use; the maintainer asks that production users buy a tree. Worth flagging to whoever approves dependencies so it isn't a surprise in a procurement review.

Watch out for mixed icon strategies. Once you're on inline SVG components, remove the Font Awesome CDN/Kite <script> or CSS from your layout. Leaving both in place means double the payload and a confusing situation where some icons inherit CSS from a webfont you're not actually using.