WP Manifestindependent plugin directory
manifest / admin / menu-icons-for-fontawesome

Menu Icons for FontAwesome

This Wordpress plugin provides searchable Font Awesome icons, category filtering, live previews, quick icon removal, automatic frontend rendering, intelligent theme-wrapper detection, and cached Font Awesome metadata.

by Marcos Ribero · github.com/markmorbid/menu-icons-for-fontawesome · website

★ 0stars
0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/markmorbid/menu-icons-for-fontawesome/archive/refs/heads/main.zip

Readme

=== Menu Icons for FontAwesome ===

Add Font Awesome icons to WordPress navigation menu items with a fast, visual icon picker built directly into the WordPress menu editor.

The plugin provides searchable Font Awesome icons, category filtering, live previews, quick icon removal, automatic frontend rendering, intelligent theme-wrapper detection, and cached Font Awesome metadata.

Features

Visual icon picker

The plugin adds a Select Icon button to WordPress navigation menu items.

The picker provides:

  • Visual icon previews
  • Search
  • Category filtering
  • Visible/total icon counts
  • Active icon highlighting
  • Tooltips showing icon names
  • A dedicated No Icon option
  • Responsive popup positioning
  • Scrollable icon grid
  • Automatic focus on the search field
  • Dynamic handling of newly added menu items

Font Awesome 7.2.0

The plugin currently loads:

Font Awesome Free 7.2.0

Font Awesome CSS is loaded from the pinned jsDelivr package:

@fortawesome/fontawesome-free@7.2.0

The plugin retrieves icon metadata from the Font Awesome 7.x metadata repository.

Only icons reported by Font Awesome metadata as having free styles are included. Pro-only icons are excluded so the picker does not offer icons that cannot be rendered by the bundled Font Awesome Free stylesheet.

The current UI is designed around the free:

  • Solid
  • Regular
  • Brands

styles.

How It Works

The plugin stores the selected Font Awesome class for each WordPress menu item in post meta:

_menu_item_icon_class

For example:

fa-solid fa-house

When the menu is rendered on the frontend, the plugin reads that value and injects the corresponding icon:

<i class="fa-solid fa-house" aria-hidden="true"></i>

The icon is inserted into the menu item's output before the menu label.

Installation

WordPress Admin

  1. Upload or install the plugin.

  2. Activate Menu Icons for FontAwesome.

  3. Go to:

    Appearance → Menus

  4. Expand any menu item.

  5. Click Select Icon.

  6. Search or browse the available icons.

  7. Select an icon.

  8. Save the menu.

The selected icon will automatically appear on the frontend.

Manual Installation

Upload the plugin directory to:

/wp-content/plugins/menu-icons-for-fontawesome/

Then activate it from:

WordPress → Plugins

Using the Icon Picker

After expanding a menu item, the plugin replaces the raw Font Awesome class field with a visual interface.

Click:

Select Icon

The icon picker opens next to the menu item.

Search

Use the search field to find icons by:

  • Icon name
  • Font Awesome label
  • Font Awesome search terms

Examples:

house
warning
arrow
user
facebook

Search is debounced to avoid unnecessary filtering while typing.

Categories

The category selector allows the available icons to be filtered using Font Awesome's category metadata.

The picker displays the number of matching icons for each category.

Icon Counts

The picker can display:

visible / total

For example:

48 / 2050

Counts can be enabled or disabled from the picker settings menu.

The preference is stored locally in the browser.

Removing an Icon

When a menu item already has an icon, hover over its menu-item title.

A small remove button appears over the icon.

Clicking it displays a confirmation strip:

Remove icon?    Remove    Cancel    Don't ask again

You can choose Don't ask again if you want subsequent removals to happen immediately.

The preference is stored locally in the browser.

The settings menu also provides:

Reset all settings

which restores the plugin's default local preferences.

About & Help

The picker includes an integrated About/Help panel containing:

  • Plugin version
  • Font Awesome version
  • Free-tier information
  • Font Awesome license information
  • Font Awesome GitHub reference
  • Usage tips
  • WordPress.org link
  • Issue tracker link

The modal can also be closed with the Escape key.

Frontend Rendering

The plugin automatically loads the Font Awesome stylesheet on the frontend.

Selected icons are injected into navigation menu markup using WordPress's:

walker_nav_menu_start_el

filter.

The generated icon includes:

aria-hidden="true"

so decorative menu icons are not unnecessarily announced by screen readers.

Basic spacing is automatically applied:

.menu-item a > i[class*="fa-"] {
    margin-right: 0.4em;
    width: 1.1em;
    text-align: center;
    vertical-align: middle;
}

Theme Compatibility

The plugin attempts to insert the icon into the menu label rather than blindly prepending it to the entire menu item.

It currently recognizes these common menu-label wrappers:

Theme / Ecosystem Wrapper
Enfold .avia-menu-text
Astra / OceanWP / some builders .nav-link-text
GeneratePress .menu-text
Kadence .link-text
Blocksy / Neve .menu-label

If one of these wrappers is present, the icon is inserted immediately after the opening wrapper.

If none is found, the plugin falls back to inserting the icon immediately after the opening <a> element.

This makes the plugin usable with a wide range of themes and menu implementations.

Custom Theme Integration

The frontend wrapper detection is intentionally extensible.

The plugin exposes the:

fami_theme_patterns

filter.

You can add additional menu-label patterns without modifying the plugin.

Example:

add_filter('fami_theme_patterns', function ($patterns) {
    $patterns[] = '<span class="my-theme-menu-label">';
    return $patterns;
});

The plugin will then attempt to inject the icon inside that wrapper.

Important

The filter expects the actual opening HTML fragment generated by the theme.

For example:

'<span class="my-theme-menu-label">'

not merely:

'.my-theme-menu-label'

This allows the existing insertion mechanism to locate the exact position in the generated menu HTML.

Font Awesome Metadata

The plugin does not maintain a manually hard-coded icon catalogue.

Instead, it retrieves Font Awesome metadata dynamically.

Icon metadata

The plugin retrieves:

metadata/icons.json

from the Font Awesome 7.x repository.

The metadata provides information such as:

  • Icon name
  • Human-readable label
  • Available free styles
  • Search terms

The plugin constructs its searchable icon dataset from this information.

Category metadata

Categories are retrieved from:

metadata/categories.yml

The plugin contains a small purpose-built YAML parser for the specific Font Awesome category format.

It does not attempt to implement a general-purpose YAML parser.

Categories are subsequently filtered so that only categories containing free icons are displayed.

Caching

Icon metadata is cached using WordPress transients.

The cache key is versioned:

fami_data_2_2_0

This means the cache automatically becomes invalid when the plugin version changes.

Normal cache duration

Successfully retrieved icon and category data is cached for:

1 month

using:

MONTH_IN_SECONDS

This prevents the plugin from repeatedly requesting the Font Awesome metadata repositories.

Failed requests

If Font Awesome metadata cannot be retrieved, the empty result is temporarily cached for:

1 hour

using:

HOUR_IN_SECONDS

This prevents repeated failed requests from generating unnecessary remote requests.

Cache invalidation

The transient is cleared during plugin:

  • Activation
  • Deactivation

The versioned transient key also naturally invalidates old cached data when the plugin version changes.

Admin Behaviour

Font Awesome CSS is enqueued in the WordPress admin using:

admin_enqueue_scripts

The icon picker itself is only initialized on the WordPress navigation menu screen.

The plugin detects:

nav-menus

before constructing the picker interface.

This keeps the picker-specific UI out of unrelated WordPress admin screens while allowing Font Awesome to be available where required.

Dynamic Menu Items

WordPress can add menu items dynamically through AJAX.

The plugin monitors the menu editor's AJAX activity and reinitializes its controls when a new menu item is added.

It also refreshes its controls after menu-item sorting.

This means newly added or rearranged menu items continue to work without requiring a full page reload.

Accessibility

The plugin includes several accessibility-oriented details:

  • aria-hidden="true" on decorative frontend icons
  • Accessible labels for picker controls
  • role="tooltip" for the singleton icon tooltip
  • role="dialog" and aria-modal="true" for the About modal
  • Accessible labels for the settings and remove controls
  • Keyboard Escape handling for closing:
    • About modal
    • Settings dropdown
    • Icon picker

The plugin's icon picker also preserves the underlying WordPress menu field rather than replacing the menu-item data model.

Data Storage

The selected icon class is stored as WordPress post meta associated with the menu item:

_menu_item_icon_class

Example:

fa-solid fa-house

The plugin does not create a custom database table.

It uses WordPress's existing post-meta system.

Security

The plugin uses standard WordPress sanitization and escaping mechanisms when handling menu-item icon values.

When the menu is saved, the submitted icon class is:

sanitize_text_field()

and:

wp_unslash()

is used before sanitization.

The menu save operation also verifies the WordPress navigation-menu nonce when available.

The plugin intentionally avoids requiring the nonce during AJAX menu-item creation requests because those requests do not contain the full navigation-menu save nonce.

Frontend icon classes are escaped with:

esc_attr()

before being inserted into generated markup.

External Resources

The plugin retrieves Font Awesome assets and metadata from external services.

Font Awesome CSS

The Font Awesome Free stylesheet is loaded from jsDelivr:

https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@7.2.0/css/all.min.css

Font Awesome icon metadata

Icon metadata is retrieved from:

https://raw.githubusercontent.com/FortAwesome/Font-Awesome/refs/heads/7.x/metadata/icons.json

Font Awesome categories

Category metadata is retrieved from:

https://raw.githubusercontent.com/FortAwesome/Font-Awesome/refs/heads/7.x/metadata/categories.yml

The metadata requests use WordPress's:

wp_remote_get()

API.

Browser Storage

The picker stores a small number of user-interface preferences in browser localStorage.

Current keys include:

fami_show_counts
fami_skip_remove_confirm

These settings are local to the browser and are not stored in the WordPress database.

Plugin Settings

There is intentionally no WordPress settings page.

The plugin is designed to work immediately after activation.

The available UI preferences are exposed through the picker settings menu.

Current settings include:

Show icon counts

Controls whether the picker displays the visible/total icon counter.

Default:

Enabled

Skip remove confirmation

Controls whether removing an icon requires confirmation.

Default:

Confirmation enabled

Both preferences can be reset through:

Settings → Reset all settings

inside the icon picker.

Requirements

Requirement Version
WordPress 5.0+
PHP 7.2+
Font Awesome 7.2.0
License GPLv2 or later

The plugin's current WordPress compatibility metadata declares:

Tested up to: 6.9

Plugin Information

Plugin Name: Menu Icons for FontAwesome

Version: 2.2.0

Author: Marcos Ribero

Contributor: Satoshisea

Text Domain:

menu-icons-for-fontawesome

License: GPLv2 or later

License URI:

https://www.gnu.org/licenses/gpl-2.0.html

Plugin URI:

https://satoshisea.io/

Developer API

fami_theme_patterns

Filter the list of HTML opening tags used to locate the menu-label insertion point.

add_filter('fami_theme_patterns', function ($patterns) {
    $patterns[] = '<span class="my-menu-text">';
    return $patterns;
});

The patterns are evaluated in order.

The first matching pattern is used.

If no pattern matches, the plugin falls back to inserting the icon immediately after the opening <a> tag.

Internal Architecture

The plugin is implemented as a single PHP plugin file and is divided into several functional layers.

Constants

Defines:

  • Plugin version
  • Font Awesome version
  • Font Awesome CSS URL
  • Metadata URL
  • Category URL
  • Versioned transient key

Metadata parser

Retrieves and parses Font Awesome metadata.

Cache layer

Stores the generated icon/category dataset in a WordPress transient.

Admin integration

Adds Font Awesome to the admin and provides the menu-item icon field.

Picker UI

Builds the complete icon picker interface dynamically using JavaScript.

Menu persistence

Stores the selected icon class in menu-item post meta.

Frontend renderer

Injects the selected icon into generated WordPress menu markup.

Read the full README on GitHub →