aryehraber/statamic-font-awesome
A Statamic addon by aryehraber that integrates Font Awesome, providing fieldtypes and template tags to easily select, manage, and render Font Awesome icons in your content and templates.
The package renders SVG icons as Blade-renderable output, and the headline change in v2.2.0 is that you can now append your own CSS classes to the rendered <svg> element rather than being stuck with whatever the icon file or the package default provides.
Start here:
composer require the package, then check whether it auto-discovers icons from resources/svg, a vendor path, or a set you register yourself. That decision determines where you drop new .svg files, so settle it before writing any markup.php artisan vendor:publish --tag=<package>-config. This is where icon sets/paths and any global default attributes live.Typical first use case: a nav or button component where you need class="w-5 h-5 text-gray-500" on the icon and expect it to actually land on the <svg> tag, not get swallowed.
Pass classes at the call site for one-offs.
<x-icon name="heroicon-o-bell" class="h-5 w-5 text-gray-500" />
Good for isolated cases in a single view. Don't let this pattern spread across hundreds of templates — you'll be grepping for h-5 later.
Wrap it in an application-level component. The reliable long-term pattern is your own <x-app.icon> that forwards $attributes and merges classes:
{{-- resources/views/components/app/icon.blade.php --}}
@props(['name', 'size' => 'md'])
@php
$sizes = ['sm' => 'h-4 w-4', 'md' => 'h-5 w-5', 'lg' => 'h-6 w-6'];
@endphp
<x-icon
:name="$name"
{{ $attributes->merge(['class' => $sizes[$size] . ' shrink-0']) }}
/>
This gives you one place to enforce sizing, shrink-0, and aria-hidden defaults, and it means the v2.2.0 class feature is exercised through a single seam rather than scattered inline.
Treat class passthrough as a styling API, not an escape hatch. Once classes flow through to the SVG, resist the urge to put complex utility strings at call sites. Expose size, variant, or color props on your wrapper and keep the utility soup inside it. When a design change lands ("all icons go from 20px to 24px"), you change one file.
Icon sets by context. Register multiple sets (heroicons, brand logos, custom product icons) and namespace them by name or directory. Use the outline/solid distinction deliberately rather than mixing both in the same surface — the mismatch is visually obvious and reviewers will flag it.
Server-rendered contexts are the real win. Because the output is inline SVG, icons work identically in Blade views, Mailables, Blade-based PDF generation (DomPDF/Snappy), and Notification templates. There's no asset pipeline or image path to resolve — which is exactly why teams reach for this instead of <img src>.
Pair with currentColor. Icons that use fill="currentColor" / stroke="currentColor" inherit the parent's text color, so text-red-500 on a wrapper colors the icon for free. Verify your icon source actually uses currentColor; some downloaded SVGs hardcode #000.
Test the render, not the file. An icon assertion is cheap and catches broken names after a set refactor:
$this->get('/')->assertSee('<svg', false);
Class merging order is not CSS override order. If the icon file or package default already ships a class attribute, your appended classes don't replace it — they concatenate. Since CSS specificity is equal, the one that wins is whichever the stylesheet defines last, which is not what you want. If you need a hard override, prefer stripping defaults in config or use merge() with a clear baseline rather than relying on ordering.
Clear the view cache after adding icons. Icons are resolved at render time from a file path, but Blade will happily serve a compiled component that references an icon name that no longer exists (or miss one that does). php artisan view:clear is the first thing to try on "the icon is there but it won't render." Same for config:clear after touching the published config.
Name-to-path resolution is the usual silent failure. A .svg in the wrong directory, a case mismatch (Bell.svg vs bell), or an extra nesting level all produce a "missing" icon or an empty string rather than a loud error. Confirm the exact name string against the filesystem.
Don't run config:cache in local dev while iterating on icon sets. A cached config pins your paths, and newly added directories won't be picked up until you re-cache. Expect at least one confusing afternoon here.
Deployment checklist: view:cache + config:cache in the deploy script, and make sure the icon directory is included in the artifact. Icons stored outside resources/ (e.g. in a gitignored or build-excluded folder) are a classic "works locally, 500s in production" bug.
Watch the SVG payload. Inline SVG means every icon is part of the HTML document. A page with 60 icons and verbose path data bloats the response and hurts TTFB. For icon-heavy UIs, consider a sprite sheet or a small cache layer rather than rendering everything inline.
Accessibility is on you, not the package. Decorative icons need aria-hidden="true"; meaningful icons need role="img" plus aria-label. Bake this into your wrapper component with a label prop — retrofitting aria attributes across a live app is miserable.
Extension points to know about: the published config (paths, sets, defaults), the underlying Blade component class if you need to subclass or override rendering, and your own wrapper component. Reach for the wrapper first — overriding the package internals couples you to its release cadence, and v2.2.0's class support means you probably no longer need to fork for styling concerns.
Upgrade note: v2.2.0 is additive — it grants new capability without changing existing behavior. Existing <x-icon> calls continue to render as before, so it's a safe bump. The only thing to audit is any place you previously bolted size/color onto a parent element as a workaround; those wrappers can now be simplified, but leave them alone unless you're actively touching that view.
How can I help you explore Laravel packages today?