Search by

mickey-kay / better-font-awesome

McGuive7

Better Font Awesome

Package info

github.com/MickeyKay/better-font-awesome

pkg:composer/mickey-kay/better-font-awesome

Security

Advisories: 0

Aikido package health analysis

Transparency log

Statistics

Installs: 17

Dependents: 0

Suggesters: 0

Stars: 11

Open Issues: 16

3.1.0 2026-09-08 15:43 UTC

Requires

Requires (Dev)

Suggests

None

Provides

None

Conflicts

None

Replaces

None

GPL-2.0-or-later 1c7a6fc651870138b8e48a56206d4243e16ffefa

Published on Packagist.org on 2026-09-08 18:47 UTC

This package is auto-updated.

Last update: 2026-09-08 18:47:27 UTC

README

CI Downloads License: GPL v2 or later

Better Font Awesome

Contributors: mcguive7, aaronbmm, mightyminnow
Tags: font awesome, icons, icon font, shortcode, block editor
Donate link: https://mickeykay.me
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 3.1.0
License: GPLv2+
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add Font Awesome Free icons that stay current automatically, with a native WordPress block, shortcodes, a Classic Editor picker, and legacy support.

Description

Do you find this plugin helpful? Please consider leaving a 5-star review.

Add Font Awesome Free icons to WordPress using a native Icon block, shortcodes, the Classic Editor picker, or HTML. Search the latest compatible Free catalog, customize icons in the Block Editor, and keep established Font Awesome 4 and 5 content working.

A built-in fallback means icons work immediately. Better Font Awesome automatically keeps Font Awesome Free icons current with newer compatible releases in the background, while pages and editors keep loading normally.

Key features

  • Native Icon block - search the latest compatible Font Awesome Free icons and styles, then adjust size, color, spacing, alignment, and an optional accessible label.
  • Flexible workflows - use the block, shortcodes, the Classic Editor picker, or HTML and CSS.
  • Automatic icon updates - start with the built-in fallback and receive newer compatible icons automatically in the background.
  • Legacy compatibility - keep established Font Awesome 4 and 5 content working, with optional controls for older or competing styles.

Getting started

Native Icon block

In the Block Editor, insert the Font Awesome Icon block. Choose an icon and available Free style, then use WordPress controls for font size, text color, margin, padding, and left, center, or right alignment. Add an accessible label when the icon communicates meaning, or leave it empty for a decorative icon.

The Icon block is a standalone block that works in layouts such as Groups, Rows, and Columns. To place an icon directly within a line of text, use the shortcode.

Shortcodes

Use the [icon] shortcode wherever WordPress processes shortcodes:

[icon name="flag" class="2x spin border" unprefixed_class="my-custom-class"]

The fa- and icon- prefixes are optional in shortcode attributes, and established prefixed forms continue to work.

Classic Editor picker

In the Classic Editor visual toolbar, choose Insert Icon, search the Free catalog, and select an icon. The picker inserts the matching shortcode into your content.

HTML and CSS

You can also use Font Awesome classes in HTML or CSS. Unlike shortcodes, HTML class prefixes are required and depend on the selected style. For current syntax, see the Font Awesome guide to adding icons.

Automatic icon updates and built-in fallback

Font Awesome Free CSS, fonts, and icon data ship with the plugin, so icons render immediately after activation. With Serve Font Awesome locally unchecked (the default), a scheduled task checks for the latest compatible release in the background and uses it only after validation. If a check is delayed or fails, the last validated release or built-in fallback stays active.

Optional local delivery

Under Settings > Better Font Awesome, check Serve Font Awesome locally to serve the bundled Font Awesome 7 Free catalog, CSS, compatibility styles, and fonts from your site. This mode disables BFA background metadata and asset-validation requests. New icons arrive through plugin updates. It never falls back to third-party assets if bundled files are unavailable.

The bundled catalog may be older than a previously adopted automatic release. Icons introduced after the bundled version will not render until a plugin update includes them or you switch back to automatic delivery. Existing content and stored metadata are preserved; switching back reuses valid metadata and schedules a background check when needed. Settings saving does not wait for remote metadata. A refresh already running when the setting changes cannot be retroactively canceled.

The settings page reports the effective delivery mode. If a theme, plugin, or initialization filter has already selected the shared library configuration, BFA preserves that selection and explains any mismatch. Explicit Font Awesome 5 ownership cannot be combined with local delivery. Local delivery does not control other plugins, themes, or site infrastructure that rewrites asset URLs to a CDN.

Compatibility and conflicts

Established Font Awesome 4 and 5 shortcode names and classes are supported through compatible aliases and styles, plus an optional Font Awesome 4 CSS shim. Font Awesome Pro and a separate Font Awesome 6 channel are not provided.

If a theme or another plugin also loads Font Awesome, go to Settings > Better Font Awesome and enable Remove existing Font Awesome. This can reduce duplicate or conflicting styles, but no automatic conflict tool can cover every theme or plugin integration.

Installation

  1. Install and activate Better Font Awesome from Plugins > Add New.
  2. Add the Font Awesome Icon block, use an [icon] shortcode, or choose Insert Icon in the Classic Editor. Optional compatibility controls are under Settings > Better Font Awesome.

Frequently Asked Questions

Does Better Font Awesome support Font Awesome Pro?

No. Better Font Awesome supports Font Awesome Free.

Do visitors download fonts from another service?

Check Serve Font Awesome locally to keep BFA's bundled CSS and fonts on your site, subject to your site's URL-rewriting infrastructure. In automatic mode, the packaged fallback also loads from your site. If the plugin validates and adopts a newer compatible release, visitors' browsers may load that release's selected CSS and font files from cdnjs.

Will existing Font Awesome 4 and 5 content keep working?

Established shortcode names and classes are supported through compatible aliases and styles. For Font Awesome 4 content, enable the optional CSS shim when needed. Unusual custom markup or CSS may still need site-specific adjustments.

What if another plugin or theme loads Font Awesome?

Enable Remove existing Font Awesome under Settings > Better Font Awesome to attempt to remove competing styles and shortcodes. Test the result with your theme and plugins because integrations vary.

External services

Better Font Awesome works immediately from its built-in Font Awesome Free fallback. In automatic mode, it uses the following external services for background updates or for assets from a newer validated release. Effective local mode makes no BFA/BFAL requests to these services. Other site components and site CDN infrastructure remain outside this setting. No Font Awesome account or API token is required for the Free channel.

  • Font Awesome GraphQL API (https://api.fontawesome.com) - an asynchronous server-side WP-Cron worker requests the latest public compatible Font Awesome Free release version, icon names, aliases, families, and styles. Review the Font Awesome terms of service and privacy policy.
  • npm registry (https://registry.npmjs.org/%40fortawesome%2Ffontawesome-free/{version}) - when Font Awesome reports a newer candidate, the same background worker confirms that exact official Free package version, name, and license. Review the npm terms and privacy notice.
  • cdnjs asset service (https://cdnjs.cloudflare.com/ajax/libs/font-awesome/{version}/) - the background worker downloads an allowlisted set of exact-version CSS and WOFF2 files for validation. BFAL does not call a separate cdnjs catalog API. After a newer release passes every check, visitors' browsers may request its selected CSS and referenced font files from this host. Review the cdnjs service information, Cloudflare website terms, and Cloudflare privacy policy.
  • jsDelivr asset service (https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@{version}/) - the background worker independently downloads the same allowlisted files and requires their bytes to match cdnjs. BFA does not select jsDelivr as the browser runtime host. Review the jsDelivr terms and policies.
  • Legacy Font Awesome 5 CDN (https://use.fontawesome.com/releases/) - if another plugin or theme deliberately initializes BFAL first and selects the legacy 5.x channel, visitors' browsers may request that selected version's CSS and fonts from this host.

Normal frontend, administrator, REST, editor, settings, shortcode, picker, and getter requests do not perform BFA or BFAL metadata discovery or candidate asset-validation HTTP. Separately, WordPress core may fetch a registered external editor stylesheet while constructing Block Editor assets; that core behavior is not a BFA or BFAL metadata-validation request.

Server-side provider requests expose ordinary connection data such as the server IP address, requested URL and version, timing, and HTTP headers. WordPress's default HTTP user agent may include the WordPress version and site URL. Browser asset requests can expose ordinary connection data such as the visitor's IP address, user agent, referring page, and requested asset. BFA does not add post content, user content, Font Awesome credentials, or an API token to these requests. In automatic mode, if discovery, publication, transport, or validation fails, BFA continues using the packaged fallback or validated last-known-good release.

Support

Need help? Start a topic in the WordPress.org support forum. Developers can also report reproducible issues on GitHub.

If Better Font Awesome helps your site, please consider leaving a brief WordPress.org review.

Screenshots

  1. Search the Font Awesome Free catalog, choose an available style, and add an accessible label.
  2. Adjust icon alignment, size, color, and spacing with WordPress block controls.
  3. Combine standalone Icon blocks with text in a polished frontend layout.
  4. Search and insert a matching shortcode with the Classic Editor picker.
  5. Review the active Font Awesome version and optional compatibility settings.

Changelog

3.1.0

  • Adds the optional Serve Font Awesome locally setting for loading the bundled Font Awesome Free catalog, CSS, and fonts from your site.
  • Keeps automatic delivery as the default. When local delivery is enabled, new icons arrive through plugin updates.

3.0.1

  • Fixes a false metadata validation warning after upgrading a site with valid retained Font Awesome 5 cache data to the default Font Awesome 7 channel.

3.0.0

  • Adds automatic updates for the current Font Awesome Free catalog with a built-in fallback.
  • Adds a native Icon block with catalog search, style and design controls, alignment, and accessible labels.
  • Preserves existing shortcodes, settings, integrations, Classic Editor picker, and Font Awesome 4 and 5 compatibility.

Older release history is preserved in the project's historical changelog.

Upgrade Notice

3.1.0

Adds optional Serve Font Awesome locally delivery. Automatic delivery remains the default; local icons update through plugin updates. Existing settings and content are preserved.

3.0.1

Removes a false post-upgrade Font Awesome metadata warning while preserving legacy cache data, safe fallback rendering, and background-only updates.

3.0.0

Adds automatic Font Awesome Free icon updates, a built-in fallback, and the native Icon block while preserving existing settings, shortcodes, and Classic Editor workflows. Requires WordPress 6.5+ and PHP 7.4+.