how-to-guide

How to Create Custom Icon Kits in Font Awesome 7: A Complete Developer's Guide

March 1, 2026 FortAwesome/Font-Awesome ↗

Font Awesome 7 lets you generate a lightweight, custom icon kit containing only the icons you need, which can be embedded via a single CDN script tag or imported through the npm packages in the FortAwesome/Font-Awesome repository.

A custom icon kit is a curated subset of Font Awesome icons bundled with optimized CSS/JS configuration. According to the Font Awesome 7 source code, kits are recognized by diagnostic markers and support a dedicated kit style (short prefix fak) that functions alongside standard solid, regular, and brand styles.

How Custom Icon Kits Work in Font Awesome 7

The Font Awesome 7 runtime contains specific logic to detect and render kit-based icons. In js/conflict-detection.js (lines 564-565), the library checks for the presence of fa-kits-diag and fa-kits-node-under-test elements to verify that a kit has loaded correctly.

The kit style itself is formally defined in js/fontawesome.js (lines 791-805), where the internal style name kit is mapped to its CSS prefix fak. This same mapping appears in js-packages/@fortawesome/fontawesome-svg-core/index.js (lines 794-802), ensuring consistency whether you use the CDN or the npm package approach.

Step-by-Step Guide to Creating a Custom Icon Kit

Generate Your Kit ID

  1. Log in to the Font Awesome website and navigate to Kits → Create a Kit.
  2. Name your kit and select the specific icons you want to include (you can mix solid, regular, brands, and custom uploads).
  3. Save the configuration to generate a unique Kit ID (for example, abcd1234).

Configure Kit Settings

Before finalizing, you can restrict the kit to specific icon styles, set a fallback strategy (such as loading the free library if an icon is missing), and choose your rendering technology: SVG + JS, Web Font, or both. This configuration determines what the CDN script at https://kit.fontawesome.com/[KIT_ID].js will inject into your page.

Installing Your Custom Icon Kit

Method 1: CDN Script Tag (Simplest)

Add the generated script to your HTML <head> or before the closing </body> tag:

<script 
  src="https://kit.fontawesome.com/abcd1234.js" 
  crossorigin="anonymous">
</script>

When this script executes, it automatically injects the minimal CSS/JS bundle and creates the fa-kits-diag diagnostic element that js/conflict-detection.js looks for to confirm successful initialization.

Method 2: NPM Packages (Build Integration)

For projects using a JavaScript bundler, replicate the kit's "subset" philosophy by importing only selected icons from the packages shipped in the repository:

npm install @fortawesome/fontawesome-svg-core \
            @fortawesome/free-solid-svg-icons \
            @fortawesome/free-regular-svg-icons \
            @fortawesome/free-brands-svg-icons

Then register only the icons you included in your kit:

// src/icons.js
import { library } from '@fortawesome/fontawesome-svg-core';
import { faUser, faHeart } from '@fortawesome/free-solid-svg-icons';
import { faSmile } from '@fortawesome/free-regular-svg-icons';
import { faGithub } from '@fortawesome/free-brands-svg-icons';

library.add(faUser, faHeart, faSmile, faGithub);

Using Kit Icons in Your Project

Once installed, use standard Font Awesome syntax. For icons from standard styles:

<i class="fa-solid fa-user"></i>
<i class="fa-regular fa-smile"></i>
<i class="fa-brands fa-github"></i>

If your kit includes a custom kit style (defined in js/fontawesome.js), use the fa-kit class and the fak prefix:

<i class="fa-kit fa-custom-icon"></i>

In React components (after importing the library), reference the icons by their prefix and name:

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';

<FontAwesomeIcon icon={['fas', 'user']} />
<FontAwesomeIcon icon={['fak', 'custom-icon']} />

Debugging Kit Loading Issues

If icons fail to render, inspect the diagnostic elements that the Font Awesome 7 runtime creates. According to js/conflict-detection.js, the script checks for:

  • fa-kits-diag – Injected when the kit script successfully runs.
  • fa-kits-node-under-test – A hidden node used to verify CSS font-family rules are applied.

Run this debug snippet in your browser console:

const diag = document.getElementById('fa-kits-diag');
const testNode = document.getElementById('fa-kits-node-under-test');

if (diag && testNode) {
  console.log('Font Awesome kit loaded. Computed font:', 
    getComputedStyle(testNode).fontFamily);
} else {
  console.warn('Kit missing: verify your script tag and Kit ID');
}

Summary

  • Custom kits bundle only the icons you need, reducing payload size compared to loading the full library.
  • Kit detection relies on specific DOM elements (fa-kits-diag) checked by js/conflict-detection.js in the Font Awesome 7 repository.
  • Style mapping treats custom kit icons as first-class citizens via the kit style (fak prefix) defined in js/fontawesome.js and js-packages/@fortawesome/fontawesome-svg-core/index.js.
  • Installation works via CDN (single script tag) or npm (selective imports), with both methods supporting the same diagnostic and rendering pipeline.
  • Version locking ensures your kit remains on a specific Font Awesome version, preventing accidental breaking changes.

Frequently Asked Questions

What is the difference between a Kit ID and an API token?

A Kit ID (e.g., abcd1234) identifies a specific icon configuration and CSS/JS bundle hosted on Font Awesome's CDN, while an API token is used for managing licenses or downloading Pro packages via npm. The Kit ID is public and safe to embed in HTML; the API token should remain private and server-side.

Can I use custom SVG icons in a Font Awesome 7 kit?

Yes. When configuring your kit on the Font Awesome website, you can upload custom SVG icons. These are treated as part of the kit style (fak prefix) and are rendered using the same pipeline as standard icons, as implemented in js/fontawesome.js (lines 791-805).

Why does my kit load but show square boxes instead of icons?

This typically indicates a font-family mismatch or a missing style definition. Verify that the fa-kit class is present and that the fak prefix is correctly mapped in your JavaScript bundle. Check js-packages/@fortawesome/fontawesome-svg-core/index.js (lines 794-802) to ensure the kit style is registered in the library if using the npm approach.

How do I update icons in an existing kit?

Log in to the Font Awesome website, navigate to your kit's settings, add or remove icons, and save. The Kit ID remains the same, but the CDN script will serve updated assets. Clear your browser cache or increment the version parameter in the script URL if changes do not appear immediately.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →