Download the PHP package justinholtweb/craft-awesemo without Composer

Awesemo

Font Awesome, managed — for Craft CMS 5.

One place decides which version the site is on. Everyone who writes anything gets a searchable icon picker. Templates get one call that renders an icon properly, as a web font or as inline SVG, and switching between those is a setting rather than a find-and-replace.

Free. No editions, no licence key.

It is the Craft answer to WordPress's Better Font Awesome, and then the parts a shortcode plugin cannot do.

Documentation: justinholt.com/plugins/craft-awesemo/docs — installation, configuration, usage, troubleshooting, FAQ.

What it does

Chooses the version, once. CDN (jsDelivr or cdnjs), a Font Awesome kit, a self-hosted package, or nothing at all when the site already loads its own. Pin an exact release or follow a line like 6; either way the control panel can tell you which version is actually live.

Removes the second copy. Two copies of Font Awesome on one page is the most common way icons break in a CMS: whichever stylesheet loads last owns the class names, and half the site goes blank. Awesemo strips Font Awesome stylesheets and kit scripts that something else put on the page, and never its own.

Puts a picker everywhere an author writes. A control-panel browser, an Icon field, a CKEditor toolbar button and a Redactor toolbar button — all four search the same catalogue, so what an author sees is the same wherever they are.

Keeps old names working. fa fa-thumbs-o-up renders as fa-regular fa-thumbs-up, through Font Awesome's own v4 shim data. Nearly 400 retired names resolve on a stock free install.

Renders three ways. Web font, inline SVG (no stylesheet, no font download), or a <use> reference into a sprite built from the icons this site actually uses.

Says what is wrong. A health screen for the things that fail silently: names that no longer exist, a stylesheet subset that misses a style the content needs, a stale catalogue, an unreachable CDN, SVG mode with no path data, another copy of Font Awesome in a template.

Templates

craft.awesemo has the rest: icon(), render(), exists(), search(), styles(), categories(), head(), css(), version(), source(), spriteUrl(), unicode().

Every icon is aria-hidden="true" unless you give it a label, at which point it becomes role="img" with that label. That is the right default: nearly every icon in a CMS sits beside text that already says what it means.

Options

mode · size · fixedWidth · listItem · rotate · flip · animation · spinReverse · border · pull · swapOpacity · inverse · class · label · title · id · color · tag. Anything else you pass becomes an HTML attribute.

Fields

Icon — one icon. The value is an Icon, which renders itself. Icons — an ordered list of them.

Both can be restricted to particular styles, given a default, and optionally let the author set size and fixed width per value.

Both are in GraphQL as an AwesemoIcon type — name, style, family, classes, code point, SVG path data, a complete <svg>, or the same markup {{ entry.icon }} renders — so a headless front end needs no Twig at all:

Rich text

CKEditor and Redactor each get a toolbar button that opens the picker and inserts plain markup:

No shortcode, no reference tag, nothing needed at render time — which means an icon written this way survives the plugin being removed, and moves between editors untouched. (Redactor gets a <span> rather than an <i>, because Redactor rewrites <i> to <em>. Font Awesome renders from the classes and does not care which element carries them.)

If the site later switches to inline SVG, |awesemoIcons upgrades everything an author already wrote, in all three elements.

Custom icons

Upload an SVG, give it a name, use it exactly like a Font Awesome one:

Uploads are sanitised on the way in — script, external references and event handlers removed — and rendered inline, so they inherit color and font-size like every other icon.

The console

awesemo/health/check in a deploy pipeline is the point: a build that would have shipped a page of blank squares fails where somebody is looking.

How it stores things

Two database tables: one for uploaded icons, one holding a copy of everything in storage/awesemo/ except the subset. The files are what requests read:

On a stock Font Awesome 6 free install that is a 57 KB file on the hot path and a 1.4 MB one that a normal request never opens. <key> hashes the source config, so changing version or kit builds a new catalogue beside the old one — and changing back is instant.

The database copy is for hosts where storage/ does not outlive the server: Craft Cloud, containers, load-balanced servers. A server that lacks a file restores it from its row the first time something asks, so a new container starts with the catalogue, the sprite and the usage scan already there. Nothing is downloaded again. The subset is left out on purpose: each server rebuilds its own from the path data, one icon at a time.

Requirements

Craft CMS 5.3+, PHP 8.2+. No runtime dependencies. CKEditor and Redactor integrations activate only when those plugins are installed.

Installation

Licence

See LICENSE.md.