# Font Awesome 7 Shims for Legacy Icon Name Support: Complete Implementation Guide
> Seamlessly upgrade your projects with Font Awesome 7 shims. This guide provides a complete implementation for legacy icon name support, ensuring zero-code-change migrations.
- Repository: [Font Awesome/Font-Awesome](https://github.com/FortAwesome/Font-Awesome)
- Tags: how-to-guide
- Published: 2026-03-01
---
**Font Awesome 7 shims automatically translate legacy Font Awesome 4 class names to modern icons, enabling zero-code-change upgrades for existing projects.**
Font Awesome 7 shims serve as a critical compatibility layer for development teams maintaining legacy codebases. This system maps deprecated icon identifiers—such as `fa-arrow-circle-o-down`—to their modern equivalents like `fa-circle-down`, ensuring visual consistency without requiring HTML or CSS modifications. As implemented in the FortAwesome/Font-Awesome repository, the shim architecture combines YAML-based metadata with runtime JavaScript translation.
## What Are Font Awesome 7 Shims?
**Font Awesome 7 shims** are a backward-compatibility mechanism designed to handle the breaking changes introduced between Font Awesome 4 and modern versions. When you include the shim layer in your project, the library intercepts legacy `fa-*` class names and substitutes the appropriate Font Awesome 7 icon and style prefix.
The system supports both JavaScript and CSS-only implementations, making it adaptable to diverse project architectures—from static HTML sites to complex React applications.
## How the Shim Architecture Works
The Font Awesome 7 shim system operates through three coordinated components: a canonical mapping definition, a JavaScript runtime loader, and a CSS compilation layer.
### The Mapping Source ([`metadata/shims.yml`](https://github.com/FortAwesome/Font-Awesome/blob/main/metadata/shims.yml))
The authoritative source of truth for all legacy-to-modern translations lives in [`metadata/shims.yml`](https://github.com/FortAwesome/Font-Awesome/blob/main/metadata/shims.yml). This YAML file defines every supported legacy name alongside its modern replacement and required style prefix.
```yaml
arrow-circle-o-down:
prefix: far
name: circle-down
```
During the build process, this file generates the runtime arrays used by both JavaScript and CSS implementations. The mapping includes hundreds of legacy icons, covering the complete Font Awesome 4 nomenclature.
### JavaScript Runtime Registration ([`js/v4-shims.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/v4-shims.js))
The [`js/v4-shims.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/v4-shims.js) file registers the mapping with the Font Awesome runtime through the global `___FONT_AWESOME___` namespace. The script contains a generated `shims` array and initialization logic:
```javascript
var shims = [
["glass", null, "martini-glass-empty"],
["envelope-o", "far", "envelope"],
["arrow-circle-o-down", "far", "circle-down"],
// ... additional mappings
];
bunker(function () {
if (typeof namespace.hooks.addShims === 'function') {
namespace.hooks.addShims(shims);
} else {
namespace.shims.push.apply(namespace.shims, shims);
}
});
```
The code checks for the presence of an `addShims` hook on the namespace object. If available, it uses the formal API; otherwise, it directly extends the `namespace.shims` array. This defensive coding ensures compatibility across different Font Awesome 7 loading scenarios.
### CSS Fallback ([`scss/v4-shims.scss`](https://github.com/FortAwesome/Font-Awesome/blob/main/scss/v4-shims.scss))
For projects that rely solely on CSS without JavaScript, [`scss/v4-shims.scss`](https://github.com/FortAwesome/Font-Awesome/blob/main/scss/v4-shims.scss) provides a Sass-based entry point:
```scss
@use 'functions';
@use 'variables' as v;
@use 'shims';
```
This file imports the necessary functions and variables, then generates compiled CSS that contains the legacy selectors. The resulting stylesheet allows browsers to render old class names correctly through CSS pseudo-elements and font-family declarations, without requiring JavaScript execution.
## Implementing Font Awesome 7 Shims in Your Project
You can activate legacy icon support through two primary methods depending on your project's JavaScript requirements.
### JavaScript Shim Installation
Include the v4-shims script after your main Font Awesome 7 JavaScript file:
```html
```
The shim script registers itself immediately upon loading, intercepting DOM observations and replacing legacy icons before they render.
### CSS-Only Shim Installation
For static sites or performance-critical applications avoiding JavaScript:
```html
```
This approach relies on the compiled CSS selectors in [`v4-shims.css`](https://github.com/FortAwesome/Font-Awesome/blob/main/v4-shims.css) to handle the translation, though it offers less flexibility than the JavaScript implementation for dynamic content.
### React and Component Frameworks
When using the official Font Awesome React library, import the shim module to register mappings before rendering components:
```jsx
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
import '@fortawesome/fontawesome-free/js/v4-shims'; // registers shims globally
export default function LegacyComponent() {
return (
);
}
```
The shim integrates with the React component's icon lookup logic, ensuring that legacy name strings passed to the `icon` prop resolve to the correct SVG paths.
## Technical Deep Dive: Runtime Lookup Process
When Font Awesome 7 parses a class list or icon reference, the resolution follows a specific fallback chain:
1. **Primary Lookup**: The system first attempts to resolve the provided name against the Font Awesome 7 icon registry using the specified prefix (`fas`, `far`, etc.).
2. **Shim Consultation**: If the primary lookup fails, the runtime checks the `namespace.shims` array populated by [`js/v4-shims.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/v4-shims.js).
3. **Translation**: A matching legacy name triggers substitution of the new icon name and optional style prefix (e.g., converting `fa` to `far`).
4. **Rendering**: The DOM receives the correct `