Icon library system for registering and managing available icon definitions. The library acts as a global registry where icon definitions must be added before they can be used with the icon rendering functions.
Global library instance for managing icon definitions throughout the application.
/**
* Global library interface for icon management
*/
interface Library {
/** Add one or more icon definitions or icon packs to the library */
add(...definitions: Array<IconDefinition | IconPack | Array<IconDefinition | IconPack>>): void;
/** Clear all icons from the library */
reset(): void;
}
/**
* Global library instance
*/
const library: Library;Basic Usage:
import { library } from "@fortawesome/fontawesome-svg-core";
import { faHome, faUser, faHeart } from "@fortawesome/free-solid-svg-icons";
import { faGithub, faTwitter } from "@fortawesome/free-brands-svg-icons";
// Add individual icons
library.add(faHome, faUser, faHeart);
// Add brand icons
library.add(faGithub, faTwitter);
// Add multiple icons at once
library.add(faHome, faUser, faHeart, faGithub, faTwitter);Multiple ways to add icons to the library for different use cases and import patterns.
/**
* Add method accepts various formats for flexible icon loading
*/
add(...definitions: Array<IconDefinition | IconPack | Array<IconDefinition | IconPack>>): void;Adding Individual Icons:
import { library } from "@fortawesome/fontawesome-svg-core";
import { faHome, faUser } from "@fortawesome/free-solid-svg-icons";
// Individual icon additions
library.add(faHome);
library.add(faUser);
// Multiple icons in one call
library.add(faHome, faUser);Adding Icon Packs:
import { library } from "@fortawesome/fontawesome-svg-core";
import { fas } from "@fortawesome/free-solid-svg-icons"; // Entire pack
import { fab } from "@fortawesome/free-brands-svg-icons";
// Add entire icon packs
library.add(fas); // All solid icons
library.add(fab); // All brand icons
// Add multiple packs
library.add(fas, fab);Adding Arrays of Icons:
import { library } from "@fortawesome/fontawesome-svg-core";
import { faHome, faUser, faHeart } from "@fortawesome/free-solid-svg-icons";
// Create icon arrays for organization
const navigationIcons = [faHome, faUser];
const actionIcons = [faHeart];
// Add arrays to library
library.add(navigationIcons);
library.add(actionIcons);
// Add multiple arrays
library.add(navigationIcons, actionIcons);Clear all registered icons from the library.
/**
* Remove all icons from the library
*/
reset(): void;Reset Usage:
import { library } from "@fortawesome/fontawesome-svg-core";
import { faHome, faUser } from "@fortawesome/free-solid-svg-icons";
// Add some icons
library.add(faHome, faUser);
// Later, clear the library
library.reset();
// Library is now empty - icons must be re-addedRetrieve registered icon definitions from the library.
/**
* Find an icon definition in the library by lookup
* @param iconLookup - Icon identification object
* @returns Icon definition if found, undefined otherwise
*/
function findIconDefinition(iconLookup: IconLookup): IconDefinition;
interface IconLookup {
prefix: IconPrefix;
iconName: IconName;
}Finding Icons:
import { library, findIconDefinition } from "@fortawesome/fontawesome-svg-core";
import { faHome } from "@fortawesome/free-solid-svg-icons";
// Add icon to library
library.add(faHome);
// Find the icon definition
const homeDefinition = findIconDefinition({
prefix: 'fas',
iconName: 'home'
});
if (homeDefinition) {
console.log('Icon found:', homeDefinition);
// IconDefinition { prefix: 'fas', iconName: 'home', icon: [...] }
} else {
console.log('Icon not found in library');
}Understanding the structure of icon definitions for library management.
/**
* Complete icon definition structure
*/
interface IconDefinition extends IconLookup {
/** Icon data tuple containing SVG information */
icon: [
number, // width in icon units
number, // height in icon units
string[], // ligatures (legacy)
string, // unicode codepoint
IconPathData // SVG path data (string or array)
];
}
/**
* Collection of multiple icon definitions
*/
interface IconPack {
[key: string]: IconDefinition;
}
/**
* SVG path data can be single path or multiple paths
*/
type IconPathData = string | string[];Icon Definition Examples:
// Example of a typical icon definition
const customIcon: IconDefinition = {
prefix: 'fas',
iconName: 'custom-icon',
icon: [
512, // width
512, // height
[], // ligatures
'f123', // unicode
'M256 8C119 8 8 119...' // SVG path data
]
};
// Add custom icon to library
library.add(customIcon);Common patterns for integrating the library system into applications.
Centralized Icon Loading:
// icons.ts - Centralized icon management
import { library } from "@fortawesome/fontawesome-svg-core";
import { faHome, faUser, faHeart, faSearch } from "@fortawesome/free-solid-svg-icons";
import { faGithub, faTwitter, faLinkedin } from "@fortawesome/free-brands-svg-icons";
// Load all application icons at startup
export function loadIcons() {
library.add(
// Navigation icons
faHome, faUser, faSearch,
// Action icons
faHeart,
// Social icons
faGithub, faTwitter, faLinkedin
);
}Lazy Icon Loading:
// Lazy load icons as needed
async function loadIconsForFeature(feature: string) {
switch (feature) {
case 'social':
const { faFacebook, faTwitter } = await import("@fortawesome/free-brands-svg-icons");
library.add(faFacebook, faTwitter);
break;
case 'navigation':
const { faHome, faUser } = await import("@fortawesome/free-solid-svg-icons");
library.add(faHome, faUser);
break;
}
}Tree-Shaking Optimization:
// Import only needed icons for optimal bundle size
import { library } from "@fortawesome/fontawesome-svg-core";
// Individual imports for tree-shaking
import { faHome } from "@fortawesome/free-solid-svg-icons/faHome";
import { faUser } from "@fortawesome/free-solid-svg-icons/faUser";
import { faGithub } from "@fortawesome/free-brands-svg-icons/faGithub";
// Add only imported icons
library.add(faHome, faUser, faGithub);