DOM Operations

/**
 * DOM interface for automatic icon replacement and CSS management
 */
interface DOM {
  /** Scan DOM and replace icon elements with SVG */
  i2svg(params?: { node: Node; callback?: () => void }): Promise<void>;
  /** Get the current CSS rules as a string */
  css(): string;
  /** Insert Font Awesome CSS into the document head */
  insertCss(): string;
  /** Start watching for DOM mutations and auto-replace icons */
  watch(): void;
}

/**
 * Global DOM instance
 */
const dom: DOM;

/**
 * Replace icon elements in the DOM with SVG
 * @param params Optional parameters for scoping and callbacks
 * @returns Promise that resolves when replacement is complete
 */
i2svg(params?: { 
  node?: Node; 
  callback?: () => void 
}): Promise<void>;

import { dom, library } from "@fortawesome/fontawesome-svg-core";
import { faHome, faUser } from "@fortawesome/free-solid-svg-icons";

// Add icons to library first
library.add(faHome, faUser);

// HTML with icon elements
document.body.innerHTML = `
  <i class="fas fa-home"></i>
  <i class="fas fa-user"></i>
`;

// Replace all icon elements with SVG
await dom.i2svg();

// Icons are now replaced with <svg> elements

// Replace icons only within a specific container
const container = document.getElementById('icon-container');

await dom.i2svg({
  node: container
});

// Only icons within the container are replaced

// Execute callback after replacement completes
await dom.i2svg({
  callback: () => {
    console.log('Icon replacement completed');
    // Perform post-replacement actions
  }
});

/**
 * Get the current Font Awesome CSS rules as a string
 * @returns CSS string containing all Font Awesome styles
 */
css(): string;

/**
 * Insert Font Awesome CSS rules into the document head
 * @returns The CSS string that was inserted
 */
insertCss(): string;

import { dom } from "@fortawesome/fontawesome-svg-core";

// Get CSS rules as string
const cssRules = dom.css();
console.log(cssRules);
// ".svg-inline--fa { display: inline-block; ... }"

// Insert CSS into document head
const insertedCss = dom.insertCss();

// CSS is now available in the document

// Generate CSS without automatic insertion
const css = dom.css();

// Create custom style element
const styleElement = document.createElement('style');
styleElement.textContent = css;
document.head.appendChild(styleElement);

/**
 * Start watching for DOM mutations and automatically replace icon elements
 */
watch(): void;

import { dom, library } from "@fortawesome/fontawesome-svg-core";
import { faHome, faUser, faHeart } from "@fortawesome/free-solid-svg-icons";

// Add icons to library
library.add(faHome, faUser, faHeart);

// Start watching for DOM changes
dom.watch();

// Now any dynamically added icon elements will be automatically replaced
setTimeout(() => {
  document.body.innerHTML += '<i class="fas fa-heart"></i>';
  // Heart icon will be automatically converted to SVG
}, 1000);

import { config, dom } from "@fortawesome/fontawesome-svg-core";

// Configure automatic behavior
config.autoReplaceSvg = true;    // Enable automatic replacement
config.autoAddCss = true;        // Automatically inject CSS
config.observeMutations = true;  // Watch for DOM changes
config.mutateApproach = 'async'; // Use async DOM mutations

// Configuration affects dom.watch() and dom.i2svg() behavior
dom.watch(); // Respects observeMutations setting

<!-- Solid icons -->
<i class="fas fa-home"></i>
<i class="fa-solid fa-user"></i>

<!-- Regular icons -->
<i class="far fa-heart"></i>
<i class="fa-regular fa-star"></i>

<!-- Brand icons -->
<i class="fab fa-github"></i>
<i class="fa-brands fa-twitter"></i>

<!-- With additional classes -->
<i class="fas fa-home text-blue-500 hover:text-blue-700"></i>

<!-- With data attributes -->
<i class="fas fa-user" data-fa-transform="rotate-90" data-fa-mask="fas fa-circle"></i>

<!-- After DOM replacement -->
<svg class="svg-inline--fa fa-home fa-fw" aria-hidden="true">
  <path d="M575.8 255.5c0 18-15 32.1-32 32.1h-32l.7 160.2c0 2.7-.2 5.4-.5 8.1V472c0 22.1-17.9 40-40 40H456c-1.1 0-2.2 0-3.3-.1c-1.4 .1-2.8 .1-4.2 .1H416 392c-22.1 0-40-17.9-40-40V448 384c0-17.7-14.3-32-32-32H256c-17.7 0-32 14.3-32 32v64 24c0 22.1-17.9 40-40 40H160 128.1c-1.5 0-3-.1-4.5-.2c-1.2 .1-2.4 .2-3.6 .2H104c-22.1 0-40-17.9-40-40V360c0-.9 0-1.9 .1-2.8V287.6H32c-18 0-32.1-14-32.1-32.1c0-9 3.4-17.4 9.7-23.5l238.2-230.1c7.1-6.9 18.6-6.9 25.7 0l238.2 230.1c6.3 6.1 9.7 14.5 9.7 23.5z"></path>
</svg>

// Batch multiple DOM changes before replacement
const container = document.createElement('div');
container.innerHTML = `
  <i class="fas fa-home"></i>
  <i class="fas fa-user"></i>
  <i class="fas fa-heart"></i>
`;

// Add to DOM once, then replace
document.body.appendChild(container);
await dom.i2svg({ node: container });

// Replace only specific sections to improve performance
const sections = document.querySelectorAll('[data-fa-section]');

for (const section of sections) {
  await dom.i2svg({ node: section });
}

import { config } from "@fortawesome/fontawesome-svg-core";

// Use async mutations for better performance
config.mutateApproach = 'async';
config.measurePerformance = true; // Enable performance monitoring

// Check if icons are in library before replacement
import { findIconDefinition } from "@fortawesome/fontawesome-svg-core";

const iconExists = findIconDefinition({ prefix: 'fas', iconName: 'home' });
if (!iconExists) {
  console.warn('Icon not found in library');
  // Add icon to library or handle missing icon
}

// Replacement with error handling
try {
  await dom.i2svg();
} catch (error) {
  console.error('Icon replacement failed:', error);
}