Font Awesome Laravel Package

Getting Started

Install the addon like any Statamic package:

composer require aerni/font-awesome

Statamic auto-discovers the service provider, so there's nothing to register manually. Publish the config (once, so you can tune the picker):

php artisan vendor:publish --tag=font-awesome-config

The addon does not ship the Font Awesome CSS itself — you're expected to load it in your layout via CDN or a local build. Add it to your <head>:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">

Then add the font_awesome fieldtype to a blueprint:

# resources/blueprints/collections/pages/page.yaml
fields:
  -
    handle: icon
    field:
      type: font_awesome
      display: Icon

You now get an icon picker in the Control Panel. First real use case: a global "site settings" or "navigation" fieldset where each link/button has an optional icon — open the picker in the CP, then render it in your Antlers layout. The field stores a Font Awesome class string (e.g. fa-solid fa-house), so rendering is just:

@if(icon)
    <i class="{{ icon }}" aria-hidden="true"></i>
@endif

Look here first when exploring: the published config/font-awesome.php (controls which icon families/styles the picker offers) and the fieldtype class under src/Fieldtypes/.

Implementation Patterns

Reusable component partial. Because the stored value is a plain class string, wrap rendering in a partial so you handle the empty case, accessibility, and any sizing in one place:

{{# resources/views/components/icon.antlers.html #}}
@if(icon)
    <i class="{{ icon }} {{ size ?? '' }}" @if(label) role="img" aria-label="{{ label }}" @else aria-hidden="true" @endif></i>
@endif

Call it with {{ partial:components/icon :icon="icon" size="fa-lg" }}.

Replicator / Grid sets. Icons work great as a field inside a set, so each block can opt into an icon:

sets:
  button:
    fields:
      - { handle: label, field: { type: text } }
      - { handle: icon, field: { type: font_awesome } }

Iterate normally — icon arrives as a string per set.

Data-driven links with a decorated list. A common pattern is storing icons on a navigation tree or a list of links and mapping them out:

<ul>
  @foreach(links as link)
    <li>
      @if(link:icon)<i class="{{ link:icon }}"></i>@endif
      <a href="{{ link:url }}">{{ link:label }}</a>
    </li>
  @endforeach
</ul>

Global settings. Put a font_awesome field on a Site global (resources/blueprints/globals/settings.yaml) or a singleton, then read it via {{ settings:some_icon }} — a cheap way to avoid hard-coding the same icons in layouts.

Config tuning by environment. The config file is where you scope the picker for editors: restrict the icon family/style so people only pick classes that match the Font Awesome build you actually ship. If your front-end loads only Solid + Brands, expose only those in the picker — otherwise editors will pick fa-regular icons that render as blank boxes because your CSS isn't there.

Augmentation / API consumption. For JSON APIs or Livewire-driven views, the stored value comes out unchanged as a string; you can pass it through to the front-end and build the <i> element in JS. No serialization surprises because there's no custom value object.

Gotchas and Tips

• You must load Font Awesome yourself. The single most common "the addon is broken" report is a blank icon picker or blank output. The addon only gives you the picker and stores a string; the glyphs come from the CSS you add to your layout (or your Vite bundle). Confirm the stylesheet actually loads on the pages where icons appear.

• Font Awesome 6 class naming. FA6 supports both the legacy fas/far/fab short forms and the newer fa-solid/fa-regular/fa-brands. Whatever the picker emits, verify your CSS build isn’t a trimmed subset (e.g. a custom subset that only kept fas) — mismatch between picker output and shipped CSS is a silent failure. If you self-host, copy the full all.min.css (or the specific solid.min.css) rather than pruning.

• The picker paginates. Icon lists are long, so the modal only renders a page of results at a time; type into the search box rather than scrolling for the one you want. Prior to v4.0.1, a previously saved icon that fell outside the initial page could fail to show as selected in the picker — if you're on an older 4.x, upgrade.

• Empty is a legitimate value. Editors can clear the field, so @if(icon) guard before rendering. Rendering <i class=""> produces nothing but clutters markup and can confuse a11y audits.

• Accessibility. Decorative icons need aria-hidden="true"; meaningful icons needs a text alternative (role="img" + aria-label, or an adjacent visually hidden <span>). Bake this into your partial so it isn't left to whoever writes the template.

• Pro icons need a Pro license AND the Pro CSS/webfont. If the config/picker offers Pro families but your license/asset pipeline doesn't include them, editors can select icons that will never render. Keep the config's exposed families in sync with your actual build.

• Don't store HTML in the field. If you build a workaround that saves <i class="..."> instead of the class string, you lose the ability to restyle (FA5→FA6, Sharp, size modifiers) without a migration. Store the class string; render markup in templates.

• Cache-busting during development. Statamic aggressively caches blueprints and the CP asset manifest. If the fieldtype doesn't appear after adding it to a blueprint, run php artisan cache:clear and php artisan statamic:stache:clear, then hard-refresh the CP. A stale CP Vue bundle is the second most common "it's broken" cause.

• __PHP_Incomplete_Class errors after upgrading. These come from serialized data cached by an older version of the addon's classes. v4.0.1 fixes the underlying cause, but on any upgrade path where you still hit it, clear the caches (php artisan cache:clear, php artisan statamic:stache:clear, and any php artisan view:clear/queue restart) before concluding the field is broken.

• Large icon sets. Rendering a big icon library in the CP costs memory; v4.0.1 reduced it noticeably. If you expose all families and still see slow or memory-exhausted pickers (or 500s in the CP on constrained hosting), narrow the families/styles in the published config — it's a config-level fix, not a code change.

• Extending the picker / output. The cleanest extension point is the published config: adjust which families/styles are offered, and (if the fieldtype supports it) the default style. For custom rendering behavior, wrap the field in your own partial or a small Antlers tag rather than fighting the fieldtype — the stored value is just a string, so anything that consumes strings can render it.

• Watch the FA major version. FA5 → FA6 renamed several icon names and removed some. If you upgrade the CSS without re-auditing saved values, previously valid icons can disappear. Grep your content for fa- class values before upgrading and diff against the FA changelog.

• Version pinning. This is a small addon (5 stars, no dependents). Pin it in composer.json to a known-good version — ^4.0.1 at minimum, since it carries real bug fixes — and read the release notes before bumping. There's minimal community pressure to catch regressions, so treat minor/major upgrades as a deliberate change, and let patch releases in.