Configuration

Settings live at Settings → Plugins → Awesemo, and every one of them can be set in config/awesemo.php instead. Nothing is marked required — a required rule would stop a fresh install saving any setting until that one field was filled in.

Where Font Awesome comes from

The whole point of the plugin: one place decides, and everything else follows.

Source	What it means
CDN	jsDelivr or cdnjs serve the free package. The default, and the only source that always has the metadata a full catalogue needs.
Kit	A Font Awesome kit, loaded by its script. Pro icons, if the kit has them.
Self-hosted	An unzipped Font Awesome package inside your own web root.
Loaded by the site itself	Awesemo delivers nothing and strips nothing. Everything else — picker, fields, editor buttons, usage scan — still works.

Version

Anything the CDN understands: 6, 6.7, 6.7.2, or latest. The default is 6.

A range is the friendlier default. Patch releases arrive without anyone doing anything, and Font Awesome does not rename icons inside a major version. The catalogue records the concrete version it resolved to, so "which version is actually live" is always answerable — from the Icons screen, from awesemo/catalog/info, or from {{ craft.awesemo.version() }}.

Two things worth knowing:

jsDelivr serves ranges; cdnjs does not. With cdnjs, a range is resolved to an exact version first, so the stylesheet URL is always concrete.
Changing the version builds a new catalogue beside the old one. Changing back is instant, because the old one is still there.

Kit

The kit code is the abc123def4 in https://kit.fontawesome.com/abc123def4.js — the code on its own, not the whole URL. A kit's icon list has no public metadata file, so the catalogue is built by parsing the kit's stylesheet. That works, with one consequence: see Catalogues built from a stylesheet, below.

Self-hosted

Point Path at the directory holding css/, webfonts/ and ideally metadata/. Aliases and environment variables are resolved, so @webroot/fontawesome and $FA_PATH both work. URL is the public path those files are served from.

The path is validated when you save: a directory that does not exist, or one with no css/ folder, is rejected with the reason. Without metadata/, SVG mode and category browsing are unavailable — again, see below.

Delivery

Setting	Effect
Automatic	The stylesheet (or kit script) is registered on every site request.
Manual	Nothing is registered until a template calls `{{ craft.awesemo.head() }}`.
Off	Nothing is ever registered.

CSS files — load all, or a subset like fontawesome, solid, brands. A subset is smaller and faster; the health screen tells you when the subset is missing a style your content actually uses.
Preload — adds <link rel="preload"> for the stylesheet.
SRI — uses Subresource Integrity hashes when the source publishes them. On by default.
Remove duplicate Font Awesome — strips Font Awesome stylesheets and kit scripts that something else put on the page. Only ever removes other copies, and only while Awesemo is delivering one itself. On by default.
Load the v4 shim stylesheet — Font Awesome's own v4-shims.css, for old markup that never passes through Awesemo at all. Off by default, because Awesemo resolves legacy names itself for everything it does render.

Delivery off + web-font mode is the one combination that breaks a site outright: web-font icons need the stylesheet, and with nothing loading it every icon is a blank square. The health screen raises that as an error rather than a warning.

Rendering

Mode is the site-wide default, and any single call can override it.

Mode	Output
`webfont`	`<i class="fa-solid fa-user">` — needs the stylesheet
`svg`	The path data, inline. No stylesheet, no font download
`sprite`	`<use href="/awesemo/sprite.svg#solid-user">` into a sprite built from the icons this site uses

SVG and sprite fall back to web-font markup when there is no path data for an icon, rather than rendering nothing.

Default style — the style assumed for a bare name like user. solid by default.
Default family — classic, sharp or duotone, for sources that have them.
Resolve legacy names — fa fa-thumbs-o-up renders as fa-regular fa-thumbs-up, through Font Awesome's own shim table. Nearly 400 retired names resolve on a stock free install. On by default.
Fallback icon — what to draw when a name resolves to nothing at all. Empty renders nothing, which is usually right: an unknown icon should cost an icon, never the page.
Register a bare icon() function — off by default, because icon is a name other plugins and other people's macros reach for too.
Sprite route — serves the generated sprite from /awesemo/sprite.svg. On by default.

Class spelling follows the version automatically: fa on v4, fas on v5, fa-solid (plus the family) on v6 and v7. You never write it.

Catalogue

Catalogue max age — how long a built catalogue is trusted before the health screen calls it stale. 30 days by default. It is a nudge, not an expiry: a stale catalogue does not break anything, it just cannot find icons added since it was built.
Allow custom icons — lets editors upload their own SVGs and use them like Font Awesome ones. On by default. Turning it off also hides the Custom icons screen.
Warn on unknown icons — logs a warning when a template or a field asks for an icon the catalogue does not have. On by default.

Catalogues built from a stylesheet

The CDN and a self-hosted package with metadata/ give a full catalogue. A kit, or a package without metadata/, is read from css/all.css instead — which is what makes those sources searchable at all.

A stylesheet lists names and code points but never says which styles an icon comes in. So a stylesheet-built catalogue claims everything as solid, recovers brands from brands.css, and marks itself as having no reliable style data. Nothing downstream then uses those style lists to tell an author their icon is unavailable. SVG mode has no path data to draw from either, and falls back to the web font.

The health screen says all of this out loud rather than leaving you to work it out.

The config file

<?php
// config/awesemo.php
return [
    'source' => 'cdn',
    'version' => '6.7.2',
    'cdnProvider' => 'jsdelivr',
    'mode' => 'svg',
    'defaultStyle' => 'regular',
    'dedupe' => true,
    'cssFiles' => ['fontawesome', 'solid', 'brands'],
];

Multi-environment works as it does everywhere else in Craft:

return [
    '*' => ['version' => '6'],
    'dev' => ['warnOnUnknownIcons' => true],
    'production' => ['version' => '6.7.2', 'preload' => true],
];

A setting in the config file is locked in the control panel, which is the usual Craft behaviour and exactly what you want for version on a site where staging and production must not drift.

Fields

Both field types are configured per field, not globally.

Allowed styles — restrict the picker to particular styles.
Default icon — what a new element starts with.
Let authors set size and fixed width — off by default; the value is then just the icon.
Maximum icons — Icons field only. 0 for no limit.

Permissions

One permission, Manage the catalogue and custom icons, under an Awesemo heading in the user group settings. It gates the destructive and expensive things: rebuilding the catalogue, running a usage scan, building the sprite, and the Custom icons screen entirely.

Without it a user can still open the Icons screen, search it, and use the picker everywhere it appears — which is the point, because that is all most authors need.

Usage — Twig, fields, rich text and the console
Troubleshooting — when icons do not appear