# Font Awesome 7 Icon Search and findIcon API: Complete Developer Guide > Master Font Awesome 7 icon search with the findIcon API. Find SVG data instantly by icon name alias or CSS class. Complete guide for developers. - Repository: [Font Awesome/Font-Awesome](https://github.com/FortAwesome/Font-Awesome) - Tags: deep-dive - Published: 2026-03-01 --- **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`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) to practical implementation in browsers and Node.js. ## How the Icon Search System Works ### The Metadata Catalog ([`metadata/icons.json`](https://github.com/FortAwesome/Font-Awesome/blob/main/metadata/icons.json)) The foundation of icon search lies in [`metadata/icons.json`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) (line 23). This function implements a three-step resolution chain: 1. **Prefix normalization**: Converts legacy `fa` to `fas` 2. **Alias resolution**: Maps search terms to canonical names via `byAlias` (e.g., `"search"` → `"magnifying-glass"`) 3. **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: ```html ``` The search terms in [`metadata/icons.json`](https://github.com/FortAwesome/Font-Awesome/blob/main/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: ```javascript 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]); // ``` ### Server-Side Icon Resolution in Node.js For CLI tools or static site generators, resolve icons server-side without browser dependencies: ```javascript 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`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js): ```javascript 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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js). ### What input formats does `parse.icon` accept in Font Awesome 7? According to the source at [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/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.