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.

What's in the package

Using the JavaScript API

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 determines what family and style an icon will render in. Below is a list of prefixes organized per Icon Pack.

Kit Custom

Classic

Duotone

Sharp

Sharp Duotone

Brands

Chisel

Etch

Jelly

Notdog

Slab

Thumbprint

Whiteboard

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)

Importing from Icon Packs

Using a prefix, you can import an individual styles for use.

// import classic solid, regular, and light
import { fas } from '@awesome.me/kit-KIT_CODE/icons'
import { far } from '@awesome.me/kit-KIT_CODE/icons'
import { fal } from '@awesome.me/kit-KIT_CODE/icons'

// import sharp solid, regular, and light
import { fass } from '@awesome.me/kit-KIT_CODE/icons'
import { fasr } from '@awesome.me/kit-KIT_CODE/icons'
import { fasl } from '@awesome.me/kit-KIT_CODE/icons'

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

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

Individual icons

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

1. Provide the fa-prefixed, camel-cased format of the icon you want to import's name (e.g. user -> faUser)
2. Include the path with the family and style the icon should render in (e.g. sharp/thin for Sharp Thin)

// import user icon in classic, regular, and light
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/classic/solid'
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/classic/regular'
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/classic/light'

// import user icon in sharp solid, regular, and light
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/sharp/solid'
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/sharp/regular'
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/sharp/light'

// import Font Awesome and Web Awesome brands
import { faFontAwesome } from '@awesome.me/kit-KIT_CODE/icons/brands'
import { faWebAwesome } from '@awesome.me/kit-KIT_CODE/icons/brands'

// import custom icon
import { faMyIcon } from '@awesome.me/kit-KIT_CODE/icons/kit/custom`

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.

"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'

Windows NPM Install

Sometimes Windows doesn't play nice with single quotes, so if you are getting path issues after installing, you may need to use double quotes.

npm install --save "@awesome.me/kit-[KIT_CODE_GOES_HERE]@latest"