deep-dive

Font Awesome 7 Icon Search and findIcon API: Complete Developer Guide

March 1, 2026 FortAwesome/Font-Awesome ↗

Font Awesome 7 resolves icon names, aliases, or CSS classes into full definition objects via the findIconDefinition API, which searches through metadata catalogs and runtime libraries to return the SVG data required for rendering.

Font Awesome 7 ships with a search-friendly metadata catalog and a runtime resolution system that enables programmatic icon discovery. This guide covers the findIconDefinition API and icon search capabilities as implemented in the FortAwesome/Font-Awesome repository, from the underlying architecture in js/fontawesome.js to practical implementation in browsers and Node.js.

How the Icon Search System Works

The Metadata Catalog (`metadata/icons.json`)

The foundation of icon search lies in metadata/icons.json, which stores a searchable map of every icon including its label, Unicode point, available styles, and an array of search terms. These terms (e.g., "search", "magnifying-glass") power the documentation search and enable runtime alias resolution.

Each entry contains structured data that the runtime uses to match user queries against canonical icon names, even when the user provides friendly labels or legacy identifiers.

Input Normalization with `parse.icon`

Before resolution, user input passes through parse.icon in js/fontawesome.js (line 66). This utility accepts multiple formats and normalizes them into a canonical { prefix, iconName } object:

String values: CSS class syntax (fa-search) or plain names (search)
Array notation: ['fas', 'search']
Object notation: { prefix: 'fas', iconName: 'search' }
Null values: Handled gracefully

The parser automatically converts legacy fa prefixes to fas (solid) to maintain backward compatibility.

The Resolution Chain (`findIconDefinition`)

The core lookup logic resides in findIconDefinition at js/fontawesome.js (line 23). This function implements a three-step resolution chain:

Prefix normalization: Converts legacy fa to fas
Alias resolution: Maps search terms to canonical names via byAlias (e.g., "search" → "magnifying-glass")
Hierarchical lookup:
- First checks library.definitions (user-added icons via library.add())
- Falls back to namespace.styles (built-in free icons from @fortawesome/free-*-svg-icons packages)

If found, the function returns an icon definition object with the shape { prefix, iconName, icon: [width, height, ligatures, unicode, svgPathData] }.

Implementing Icon Lookup in Practice

Resolving Icons in the Browser

To use the API in a browser environment, load the Font Awesome bundle and access the global FontAwesome.api object:

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.0/js/fontawesome.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.0/js/solid.min.js"></script>
</head>
<body>
  <script>
    // Access the runtime API
    const { findIconDefinition, icon } = FontAwesome.api;

    // Resolve "search" (an alias for magnifying-glass)
    const definition = findIconDefinition({ iconName: 'search' });

    console.log(definition);
    // → { prefix: 'fas', iconName: 'magnifying-glass', icon: [512, 512, [], 'f002', '…svg path…'] }

    // Generate SVG markup
    const markup = icon(definition).html[0];
    document.body.insertAdjacentHTML('beforeend', markup);
  </script>
</body>
</html>

The search terms in metadata/icons.json ensure that "search" resolves correctly to the internal "magnifying-glass" icon without requiring knowledge of the exact canonical name.

Adding and Searching Custom Library Icons

When working with the npm package @fortawesome/fontawesome-svg-core, you can add custom icons to the library and resolve them later:

import { library, findIconDefinition, icon } from '@fortawesome/fontawesome-svg-core';
import { faDog } from '@fortawesome/free-solid-svg-icons';

// Add to runtime library (class Library at js/fontawesome.js line 12)
library.add(faDog);

// Lookup works by any registered alias
const definition = findIconDefinition({ iconName: 'dog' });
console.log(definition.iconName); // "dog"

// Render to HTML
console.log(icon(definition).html[0]); // <svg …>…</svg>

Server-Side Icon Resolution in Node.js

For CLI tools or static site generators, resolve icons server-side without browser dependencies:

const { findIconDefinition } = require('@fortawesome/fontawesome-svg-core');
require('@fortawesome/free-solid-svg-icons'); // Auto-registers to namespace.styles

function resolveIcon(term) {
  const def = findIconDefinition({ iconName: term });
  if (!def) {
    throw new Error(`Icon not found for "${term}"`);
  }
  return def;
}

// Resolves "search" to magnifying-glass definition
console.log(resolveIcon('search'));

Core Implementation Details

The lookup logic follows this priority chain as implemented in js/fontawesome.js:

function findIconDefinition(iconLookup) {
  // 1️⃣ Legacy support: fa → fas
  if (iconLookup.prefix === 'fa') {
    iconLookup.prefix = 'fas';
  }

  const iconName = iconLookup.iconName;
  const prefix = iconLookup.prefix || getDefaultUsablePrefix();

  if (!iconName) return;

  // 2️⃣ Resolve aliases via namespace.aliases
  const canonicalName = byAlias(prefix, iconName) || iconName;

  // 3️⃣ Lookup: library first, then built-in namespace.styles
  return (
    iconFromMapping(library.definitions, prefix, canonicalName) ||
    iconFromMapping(namespace.styles, prefix, canonicalName)
  );
}

Key source locations to explore:

js/fontawesome.js (lines 12, 23, 66): Core Library class, findIconDefinition, and parse.icon
js-packages/@fortawesome/fontawesome-svg-core/index.js: NPM package entry point
metadata/icons.json: Master search catalog with search.terms arrays
js-packages/@fortawesome/free-solid-svg-icons/index.js: Example icon exports populating namespace.styles

Summary

metadata/icons.json contains searchable terms for every icon, enabling discovery by friendly names or aliases without knowing canonical IDs.
parse.icon (line 66) normalizes diverse input formats—strings, arrays, objects—into { prefix, iconName } objects, handling legacy fa prefix conversion.
findIconDefinition (line 23) implements a two-tier lookup: user-added library.definitions first, then built-in namespace.styles, resolving aliases via byAlias.
The API returns a complete icon definition object containing dimensions, Unicode, and SVG path data, ready for icon() or toHtml() rendering in any JavaScript environment.

Frequently Asked Questions

How does Font Awesome 7 handle icon aliases when searching?

The runtime uses the byAlias helper to consult namespace.aliases before lookup. If a user searches for "search", the system resolves this to the canonical "magnifying-glass" name before checking the library or namespace maps, as defined in the core logic at js/fontawesome.js.

What input formats does `parse.icon` accept in Font Awesome 7?

According to the source at js/fontawesome.js line 66, parse.icon accepts null, plain strings (CSS classes like fa-search or names like search), array notation ['fas', 'search'], and object notation {prefix, iconName}. It returns a normalized canonical object or null for invalid inputs.

Where does `findIconDefinition` look for icon definitions?

The function checks two locations in order: first the library.definitions map (icons explicitly added via library.add()), then the namespace.styles map (built-in icons from free packages). This hierarchy allows custom icons to override built-ins while falling back to the standard set.

Can I use `findIconDefinition` without adding icons to the library first?

Yes. If you import packages like @fortawesome/free-solid-svg-icons, they automatically populate namespace.styles at import time. findIconDefinition will locate these icons in the built-in namespace even if you never call library.add(), making it suitable for static imports and server-side rendering.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how FortAwesome/Font-Awesome works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →