or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

css-framework.mdicon-assets.mdindex.mdjavascript-api.mdscss-customization.md
tile.json

javascript-api.mddocs/

JavaScript API

The Font Awesome JavaScript API provides programmatic control over icon rendering, DOM manipulation, and library management. All functionality is available through the global FontAwesome object when using browser builds.

Core API

Main FontAwesome Object

interface FontAwesome {
  config: FontAwesomeConfig;
  dom: FontAwesomeDom;
  parse: FontAwesomeParse;
  library: FontAwesomeLibrary;
  noAuto(): void;
  findIconDefinition(iconLookup: IconLookup): IconDefinition | null;
  toHtml(abstractElement: AbstractElement): string;
  icon(iconDefinition: IconDefinition, params?: IconParams): Icon;
  layer(assembler: () => AbstractElement[], params?: LayerParams): Icon;
  text(content: string, params?: TextParams): Icon;
  counter(content: string | number, params?: CounterParams): Icon;
}

The main FontAwesome global object provides access to all Font Awesome functionality.

Configuration

interface FontAwesomeConfig {
  styleDefault: string;           // Default icon style ('solid')
  familyDefault: string;          // Default icon family ('classic')  
  cssPrefix: string;              // CSS class prefix ('fa')
  replacementClass: string;       // Replacement CSS class ('svg-inline--fa')
  autoReplaceSvg: boolean;        // Auto-replace icons with SVG (true)
  autoAddCss: boolean;            // Auto-add CSS (true)
  searchPseudoElements: boolean;        // Search pseudo-elements (false)
  searchPseudoElementsWarnings: boolean; // Warn about pseudo-elements (true)
  searchPseudoElementsFullScan: boolean; // Full scan for pseudo-elements (false)
  observeMutations: boolean;            // Observe DOM mutations (true)
  mutateApproach: string;         // Mutation approach ('async')
  keepOriginalSource: boolean;    // Keep original HTML (true)
  measurePerformance: boolean;    // Performance measurement (false)
  showMissingIcons: boolean;      // Show missing icon indicators (true)
}

Usage:

// Disable automatic SVG replacement
FontAwesome.config.autoReplaceSvg = false;

// Change default style
FontAwesome.config.styleDefault = 'regular';

// Disable performance measurement
FontAwesome.config.measurePerformance = true;

DOM Manipulation

interface FontAwesomeDom {
  i2svg(params?: I2SvgParams): Promise<void>;
  unwatch(): void;
  watch(params?: WatchParams): void;
  css(): string;
  insertCss(): void;
}

interface I2SvgParams {
  node?: Element;
  callback?: () => void;
}

interface WatchParams {
  autoReplaceSvgRoot?: Element;
  observeMutationsRoot?: Element;
}

Icon Replacement

i2svg(params?) - Convert <i> elements to SVG

// Convert all icons on the page
await FontAwesome.dom.i2svg();

// Convert icons within specific element
await FontAwesome.dom.i2svg({ 
  node: document.getElementById('content') 
});

// Convert with callback
await FontAwesome.dom.i2svg({ 
  callback: () => console.log('Conversion complete') 
});

DOM Watching

watch(params?) - Start watching for new icons

// Start watching entire document
FontAwesome.dom.watch();

// Watch specific root element
FontAwesome.dom.watch({ 
  autoReplaceSvgRoot: document.getElementById('app') 
});

unwatch() - Stop watching for changes

FontAwesome.dom.unwatch();

CSS Management

css() - Get Font Awesome CSS as string

const faStyles = FontAwesome.dom.css();
console.log(faStyles); // Returns complete FA CSS

insertCss() - Insert CSS into document head

FontAwesome.dom.insertCss(); // Adds FA styles to document

Icon Creation

Basic Icon Creation

icon(iconDefinition, params?) - Create icon elements

function icon(iconDefinition: IconDefinition, params?: IconParams): Icon;

interface IconParams {
  transform?: Transform;
  symbol?: boolean | string;
  mask?: IconLookup;
  title?: string;
  titleId?: string;
  classes?: string[];
  attributes?: Record<string, string>;
}

interface Icon {
  tag: string;
  attributes: Record<string, string>;
  children: Icon[];
  node: Element[];
  html: string[];
}

Usage:

// Create user icon
const userIcon = FontAwesome.icon({ prefix: 'fas', iconName: 'user' });
document.body.appendChild(userIcon.node[0]);

// Create icon with custom classes
const largeIcon = FontAwesome.icon(
  { prefix: 'fas', iconName: 'heart' },
  { classes: ['fa-2x', 'text-red'] }
);

// Create icon with transform
const rotatedIcon = FontAwesome.icon(
  { prefix: 'fas', iconName: 'sync' },
  { transform: { rotate: 90 } }
);

Layered Icons

layer(assembler, params?) - Create layered icon compositions

function layer(assembler: () => AbstractElement[], params?: LayerParams): Icon;

interface LayerParams {
  classes?: string[];
  attributes?: Record<string, string>;
}

Usage:

const layeredIcon = FontAwesome.layer(() => [
  FontAwesome.icon({ prefix: 'fas', iconName: 'circle' }),
  FontAwesome.icon({ prefix: 'fas', iconName: 'user' }, { 
    transform: { shrink: 6 } 
  })
]);

Text Layers

text(content, params?) - Create text layers

function text(content: string, params?: TextParams): Icon;

interface TextParams {
  transform?: Transform;
  classes?: string[];
  attributes?: Record<string, string>;
}

Usage:

const textIcon = FontAwesome.text('Hello', { 
  classes: ['fa-2x'] 
});

Counter Badges

counter(content, params?) - Create counter badges

function counter(content: string | number, params?: CounterParams): Icon;

interface CounterParams {
  classes?: string[];
  attributes?: Record<string, string>;
}

Usage:

const notification = FontAwesome.layer(() => [
  FontAwesome.icon({ prefix: 'fas', iconName: 'bell' }),
  FontAwesome.counter('3')
]);

Parsing Utilities

interface FontAwesomeParse {
  icon(iconDefinition: any): IconDefinition | null;
  transform(transformString: string): Transform;
}

interface Transform {
  size?: number;
  x?: number;
  y?: number;
  rotate?: number;
  flipX?: boolean;
  flipY?: boolean;
}

Usage:

// Parse transform string
const transform = FontAwesome.parse.transform('rotate-90 shrink-6');

// Parse icon definition
const iconDef = FontAwesome.parse.icon({ iconName: 'user', prefix: 'fas' });

Library Management

interface FontAwesomeLibrary {
  add(...iconDefinitions: IconDefinition[]): void;
  reset(): void;
}

Adding Custom Icons

add(...iconDefinitions) - Add custom icon definitions

// Add custom icon
FontAwesome.library.add({
  prefix: 'fac', // custom prefix
  iconName: 'my-icon',
  icon: [512, 512, [], 'e001', 'M123 456 L789 123...'] // SVG data
});

// Use custom icon
const customIcon = FontAwesome.icon({ prefix: 'fac', iconName: 'my-icon' });

Resetting Library

reset() - Clear all custom icons

FontAwesome.library.reset();

Icon Lookup

findIconDefinition(iconLookup) - Find icon definition by lookup

function findIconDefinition(iconLookup: IconLookup): IconDefinition | null;

interface IconLookup {
  prefix: 'fas' | 'far' | 'fab' | string;
  iconName: string;
}

interface IconDefinition {
  prefix: string;
  iconName: string;
  icon: [number, number, string[], string, string | string[]];
}

Usage:

const iconDef = FontAwesome.findIconDefinition({ 
  prefix: 'fas', 
  iconName: 'user' 
});

if (iconDef) {
  const icon = FontAwesome.icon(iconDef);
}

Utility Functions

noAuto() - Disable automatic features

FontAwesome.noAuto(); // Disables auto-replacement and CSS injection

toHtml(abstractElement) - Convert abstract elements to HTML

function toHtml(abstractElement: AbstractElement): string;

Usage:

const htmlString = FontAwesome.toHtml(iconElement);

Global Access

All JavaScript files expose the Font Awesome API globally:

  • fontawesome.js: Core API only (no icons)
  • all.js: Core API + all icon definitions
  • solid.js: Adds solid icon definitions to existing API
  • regular.js: Adds regular icon definitions to existing API
  • brands.js: Adds brand icon definitions to existing API

The global FontAwesome object is available as window.FontAwesome in browsers.