Kit Package API

Font Awesome Kits can now be installed using npm-compatible package managers. Learn about what’s included and how to use the package in JavaScript and other applications.

Before You Start

Make sure you:

• Configured access to use Font Awesome packages
• You have a project based on an npm-compatible package manager

Configure Access for Pro

What’s in the package

Asset	Location	What it’s good for
CSS	css/*	StyleSheets ready to work in any modern browser using the files in webfonts directory
Less	less/*	Less files using the webfonts directory
SCSS	scss/*	SCSS (Sass) files using the webfonts directory
Webfont Files	webfonts/*	WOFF2 and TTF webfont files for use with CSS, Less, and SCSS
Auto loading JavaScript	js/*	Easier to use JavaScript files for including in <script> tags directly in the browser using SVG + JS technology
ESM & CommonJS JavaScript	modules/*	SVG Core-compatible JavaScript files suitable for use with build tools, JS frameworks, or <script type="module"> using SVG + JS technology
SVG Sprites	sprites/*	SVG Sprites for all icons
SVG Files	svg/*	Individual SVG files for all icons
Data files	metadata/*	JSON and Yaml files containing icon data

Using the JavaScript API

A modern package for a modern world

The Kit Package uses the newer exports feature of package.json configurations. Most newer build tools and systems understand this but older tools may struggle to find modules you try to import.

byPrefixAndName[prefix][iconName]

This object contains all icons in a Kit. If you’ve subsetted a Kit this can be an easy to understand to use.

Replace KIT_CODE with your Pro Kit unique token

If you’ve added the “house icon” to your Kit, you could do the following.

import { byPrefixAndName } from '@awesome.me/kit-KIT_CODE/icons'

byPrefixAndName.fas['house']

Objects from byPrefixAndName are organized by prefix, then icon name.

byPrefixAndName.fas['house']
byPrefixAndName.far['square']
byPrefixAndName.fass['sword']
byPrefixAndName.fab['font-awesome']

Objects With individual icon objects shaped like this.

// Example icon returned
{
  prefix: 'fas',
  iconName: 'house',
  icon: [
    576,
    512,
    [63498,63500,127968,"home","home-alt","home-lg-alt"],
    'f015',
    '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-14-32-32.1c0-9 3-17 10-24L266.4 8c7-7 15-8 22-8s15 2 21 7L564.8 231.5c8 7 12 15 11 24z'
  ]
};

Prefix

The prefix fas is one of the following.

Kit Custom Family

Style	Availability	Prefix	Looks like
Kits	Pro Plan	fak	Any icon that you upload
Kits Duotone	Pro Plan	fakd	Any icon that you upload

Classic Family

Style	Availability	Prefix	Looks like
Solid	Free Plan	fas
Regular	Pro only	far
Light	Pro only	fal
Thin	Pro only	fat
Brands	Free Plan	fab

Duotone Family

Style	Availability	Prefix	Looks like
Solid	Pro only	fad
Regular	Pro only	fadr
Light	Pro only	fadl
Thin	Pro only	fadt

Sharp Family

Style	Availability	Prefix	Looks like
Solid	Pro only	fass
Regular	Pro only	fasr
Light	Pro only	fasl
Thin	Pro only	fast

Sharp Duotone Family

Style	Availability	Prefix	Looks like
Solid	Pro only	fasds
Regular	Pro only	fasdr
Light	Pro only	fasdl
Thin	Pro only	fasdt

all[]

All is an array of every icon for a Kit. This is best if the Kit you are using is using custom subsetting.

import { all } from '@awesome.me/kit-KIT_CODE/icons'

The most useful way to use all is to pair it with the SVG Core Library. The library allows you to register icons you wish to use and look them up in a variety of ways through other APIs and libraries.

import { library } from '@fortawesome/fontawesome-svg-core'
import { all } from '@awesome.me/kit-KIT_CODE/icons'

library.add(...all)

The individual icons in the all Array are just like the objects returned from byPrefixAndName.

Icon packs

One step down from using all is to import icons by their family and style.

import { library } from '@fortawesome/fontawesome-svg-core'
import { fas, fad, fasr, fak } from '@awesome.me/kit-KIT_CODE/icons'
library.add(fas, fad, fal)

Icon packs are objects keyed from icon names. But the icon names are prefixed with fa and camel-cased. So square-check becomes faSquareCheck. Since variable names in JavaScript cannot begin with numbers that’s why you see everything starting with fa.

import { library } from '@fortawesome/fontawesome-svg-core'
import { fas } from '@awesome.me/kit-KIT_CODE/icons'

library.add(fas.faSquareCheck)

Imports

Kit Custom Family

Style	Import
Kits	import { fak } from '@awesome.me/kit-KIT_CODE/icons'
Kits Duotone	Not yet available but coming soon!

Classic Family

Style	Import
Solid	import { fas } from '@awesome.me/kit-KIT_CODE/icons'
Regular	import { far } from '@awesome.me/kit-KIT_CODE/icons'
Light	import { fal } from '@awesome.me/kit-KIT_CODE/icons'
Thin	import { fat } from '@awesome.me/kit-KIT_CODE/icons'
Brands	import { fab } from '@awesome.me/kit-KIT_CODE/icons'

Duotone Family

Style	Import
Solid	import { fad } from '@awesome.me/kit-KIT_CODE/icons'
Regular	import { fadr } from '@awesome.me/kit-KIT_CODE/icons'
Light	import { fadl } from '@awesome.me/kit-KIT_CODE/icons'
Thin	import { fadt } from '@awesome.me/kit-KIT_CODE/icons'

Sharp Family

Style	Import
Solid	import { fass } from '@awesome.me/kit-KIT_CODE/icons'
Regular	import { fasr } from '@awesome.me/kit-KIT_CODE/icons'
Light	import { fasl } from '@awesome.me/kit-KIT_CODE/icons'
Thin	import { fast } from '@awesome.me/kit-KIT_CODE/icons'

Sharp Duotone Family

Style	Import
Solid	import { fasds } from '@awesome.me/kit-KIT_CODE/icons'
Regular	import { fasdr } from '@awesome.me/kit-KIT_CODE/icons'
Light	import { fasdl } from '@awesome.me/kit-KIT_CODE/icons'
Thin	import { fasdt } from '@awesome.me/kit-KIT_CODE/icons'

Shaking Those Trees

Using all and icon packs make it hard for build tools to utilize tree shaking. So if that’s something you know you want to use, try using the “Individual icons” import examples below. However, you can accomplish the same goal as tree-shaking by using a Kit that has been custom subsetted. Custom subsetting allows you to select only the family, styles, and icons that you’ll actually be using. That’s the same goal tree-shaking solves but in a less technically-focused way.

Individual icons

You can import individual icons. This has the advantage of being tree-shakable for keeping your bundles small.

import { faSquare } from '@awesome.me/kit-KIT_CODE/icons/classic/solid'
// React example
<FontAwesomeIcon icon={faSquare} />

Imports

Kit Custom Family

Style	Import
Kits	import { faMyIcon } from '@awesome.me/kit-KIT_CODE/icons/kit/custom'
Kits Duotone	Not yet available but coming soon!

Classic Family

Style	Import
Solid	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/classic/solid'
Regular	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/classic/regular'
Light	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/classic/light'
Thin	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/classic/thin'
Brands	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/classic/brands'

Duotone Family

Style	Import
Solid	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/duotone/solid'
Regular	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/duotone/regular'
Light	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/duotone/light'
Thin	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/duotone/thin'

Sharp Family

Style	Import
Solid	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/sharp/solid'
Regular	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/sharp/regular'
Light	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/sharp/light'
Thin	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/sharp/thin'

Sharp Duotone Family

Style	Import
Solid	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/sharp-duotone/solid'
Regular	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/sharp-duotone/regular'
Light	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/sharp-duotone/light'
Thin	import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/sharp-duotone/thin'

Troubleshooting

TypeScript

If you run into import errors when using TypeScript you may need to adjust your TypeScript config.

A common error caused by having the wrong moduleResolution is this.

Cannot find module '@awesome.me/kit-KIT_CODE/icons/classic/solid' or its corresponding type declarations.

To fix this, go into your tsconfig.json file and make sure the moduleResolution is set to value supported by the kit package.

Options
nodenext	Recommended
bundler	Also supported if nodenext does not work for you for some reason.
node16	Supported but not recommended because it is currently the same as nodenext and nodenext is forward looking and will be updated to support new Node.js module resolution features as they are added.
node	Unsupported
classic	Unsupported
node10	Unsupported

"moduleResolution": "bundler",

Note about incompatible TypeScript defaults

Your TypeScript implementation may default to an incompatible module or moduleResolution option. For example, as of TypeScript 5.4.2 a new project will default to using module: commonjs and will not specify moduleResolution. Unfortunately, when module is “commonjs”, then the default moduleResolution is “node10”, equivalent to “node”, which is not supported.

For more information about the moduleResolution setting, see the official TypeScript docs.

TypeScript + SVG Core APIs

Currently there two functions in the API from @fortawesome/fontawesome-svg-core that are affected by a Kit Package.

• icon()
• findIconDefinition()

Because the Kit Package can have a subset of Font Awesome icons or even custom uploaded icons, the TypeScript definitions need to be modified to be aware of these types.

Here, we can see TypeScript is reporting errors with the following code.

import { icon, findIconDefinition } from "@fortawesome/fontawesome-svg-core";
import type { IconLookup } from "@awesome.me/kit-KIT_CODE/icons";

const lookup : IconLookup = { prefix: "fas", iconName: "starship" };

icon(lookup);

findIconDefinition(lookup);

# tsc
index.ts:13:6 - error TS2345: Argument of type 'IconLookup' is not assignable to parameter of type 'IconLookup | IconName'.
  Type 'import("/path/node_modules/@awesome.me/kit-KIT_CODE/icons/modules/icon-types").IconLookup' is not assignable to type 'import("/path/node_modules/@fortawesome/fontawesome-common-types/index").IconLookup'.
    Types of property 'iconName' are incompatible.
      Type 'import("/path/node_modules/@awesome.me/kit-KIT_CODE/icons/modules/icon-types").IconName' is not assignable to type 'import("/path/node_modules/@fortawesome/fontawesome-common-types/index").IconName'.
        Type '"my-custom-icon"' is not assignable to type 'IconName'.?

13 icon(lookup);
        ~~~~~~

index.ts:15:20 - error TS2345: Argument of type 'import("/path/node_modules/@awesome.me/kit-KIT_CODE/icons/modules/icon-types").IconLookup' is not assignable to parameter of type 'import("/path/node_modules/@fortawesome/fontawesome-common-types/index").IconLookup'.

15 findIconDefinition(lookup);
                      ~~~~~~

This can be pretty confusing the first time you run into it. TypeScript is basically telling us that the arguments for icon() or findIconDefinition() have been defined in the @fortawesome/fontawesome-common-types package. That package is generic and includes every available Font Awesome icon. It’s not aware of the icons in your Kit.

We can use Module Augmentation to update the definition for both functions.

import { icon, findIconDefinition } from "@fortawesome/fontawesome-svg-core";
import type { IconLookup } from "@awesome.me/kit-d1e13f5422/icons";
import type { IconLookup, IconName } from "@awesome.me/kit-d1e13f5422/icons";

import type { IconDefinition } from "@fortawesome/fontawesome-common-types";

declare module "@fortawesome/fontawesome-svg-core" {
  export function icon(icon: IconName | IconLookup, params?: IconParams): Icon;
  export function findIconDefinition(iconLookup: IconLookup): IconDefinition;
}

const lookup : IconLookup = { prefix: "fas", iconName: "starship" };

icon(lookup);

findIconDefinition(lookup);

This will fix things up. You can place the declare module in any module (according to our testing) and you only need to add it once.

404 Error

If you get this error:

HttpErrorGeneral: 404 Not Found - GET https://registry.npmjs.com/@awesome.me%2Fkit-KIT_CODE - Not found

Try running the update command before running the install command.

npm update '@awesome.me/kit-KIT_CODE'

npm install --save '@awesome.me/kit-KIT_CODE@latest'