react-fontawesome

@fortawesome/react-fontawesome is the Font Awesome team’s own React binding, turning the SVG-with-JS Font Awesome core into a single FontAwesomeIcon component instead of raw markup or icon fonts. It wraps @fortawesome/fontawesome-svg-core’s icon() and parse() calls, converts the resulting abstract SVG tree into real React elements, and exposes the whole animation, transform, masking, and gradient API of Font Awesome 6/7 as typed props.

Version 3 is a full TypeScript rewrite of the original JS component, adding a FontAwesomeLayers component (plus LayersText/LayersCounter) for stacking icons, text, and counters, a CustomPrefixProvider for SSR frameworks like Next.js and Astro that need the CSS class prefix set before hydration, and a style-string parser with an internal LRU-style cache to avoid re-parsing repeated inline styles across renders.

Because it’s maintained by Font Awesome directly, it tracks the icon core’s release cadence closely — the CI matrix tests against both v6 and v7 of the SVG core and both React 18 and 19, so version skew between the icon set and the component is caught before release rather than discovered by consumers.

What You Get

• A FontAwesomeIcon component accepting icon lookups (['fas', 'coffee']), full IconDefinition objects, size/rotation/flip/pull props, and the complete FA6/7 animation set (spin, beat, fade, bounce, shake, and more)
• FontAwesomeLayers, LayersText, and LayersCounter components for stacking multiple icons, overlay text, and badge-style counters exactly like the Font Awesome Web docs’ layering examples
• A CustomPrefixProvider component built specifically for SSR frameworks (Next.js, Astro, Remix) so a custom CSS class prefix is set before client hydration instead of causing a flash of unprefixed classes
• Native masking and gradient-fill support (mask, gradientFill props) that generate the corresponding <mask>/<linearGradient>/<radialGradient> SVG elements automatically
• Full TypeScript types for every prop surface, generated from the same type definitions Font Awesome ships for its core packages, so icon names and animation props are checked at compile time

Common Use Cases

• Dropping Font Awesome icons into a React or Next.js app as real SVG elements instead of an icon font, avoiding FOUC and getting per-icon tree-shaking
• Building compound icon graphics (badges, notification counters, circled icons) with FontAwesomeLayers instead of stacking <span>s manually
• Configuring a custom CSS prefix for icons in an SSR app via CustomPrefixProvider so server-rendered and hydrated markup match
• Applying Font Awesome’s animation classes (spin, beat, fade) declaratively as component props instead of manually toggling CSS classes
• Rendering brand or duotone icons with gradient fills for marketing pages or dashboards without hand-authoring SVG gradients

Under The Hood

Architecture The library is a thin, well-layered conversion pipeline rather than an icon set of its own: FontAwesomeIcon.tsx normalizes whatever icon prop shape it receives (normalizeIconArgs) using @fortawesome/fontawesome-svg-core’s parse.icon, calls the core’s icon() renderer to get an abstract SVG tree, and hands that tree to converter.ts’s recursive convert() function, which walks the abstract tree and calls React.createElement for every node, remapping class→className, parsing inline style strings into CSSProperties (with an LRU-capped cache), and merging in the caller’s own DOM props/refs. FontAwesomeLayers.tsx reuses the same makeReactConverter for its LayersText/LayersCounter children, so the layering component and the base icon component share one rendering primitive rather than duplicating SVG-building logic. CustomPrefixProvider.tsx is a deliberately minimal side-effect-only component ('use client', renders null) that just writes config.cssPrefix before the app’s body mounts, addressing an SSR-hydration-specific problem cleanly rather than baking prefix logic into the icon component itself. Tech Stack Written entirely in TypeScript against a react: ^18.0.0 || ^19.0.0 and @fortawesome/fontawesome-svg-core: ~6 || ~7 peer-dependency range, built with tsup into dual ESM/CJS output plus .d.ts files, and documented via typedoc with a GitHub-themed output and umami-analytics plugin. Linting is eslint (flat config, typescript-eslint, eslint-plugin-react/react-hooks/jsx-a11y/unicorn) with prettier for formatting, and commit messages are enforced via commitlint + a conventional-commits config feeding semantic-release for versioned, changelog-generating releases. Code Quality Testing uses jest with ts-jest’s ESM preset and @testing-library/react/jest-dom, with jsdom as the test environment and code coverage collection enabled by default (collectCoverage: true, v8 provider) excluding pure type/fixture files. Tests exist for every component and utility (FontAwesomeIcon, FontAwesomeLayers, converter, camelize, gradients, normalize-icon-args, get-class-list-from-props, the accessibility-id hook, and the logger), and mock the internal Logger to assert on error/warn paths explicitly rather than letting them fail silently. CI runs a validate stage (commitlint, eslint, prettier check, tsc --noEmit) before a full build-and-test matrix across multiple Node, React, and Font Awesome core versions, so compatibility regressions across dependency versions are caught pre-merge. What Makes It Unique Rather than shipping its own icon font or duplicating Font Awesome’s icon data, the package is purpose-built as a conversion and ergonomics layer over the shared fontawesome-svg-core, which is what lets it support gradients, masks, layering, and per-icon tree-shaking uniformly across the free and pro icon sets without version drift. The CustomPrefixProvider’s narrow, side-effect-only design solving one specific SSR hydration-timing problem, and the style-string parsing cache aimed at pages rendering many icons, both read as deliberate, load-bearing performance and correctness choices rather than generic conveniences.