APIs

Icon Library

Font Awesome provides thousands of icons. The "Library" is the way you can subset or reduce file sizes and reference icons easily.

Advertisement

Font Awesome SVG Core and icon content packages

The @fortawesome/fontawesome-svg-core package provides the functionality but not any of the icon content.

npm install @fortawesome/fontawesome-svg-core

We'll be using the library object which is part of the API. Install one of the icon content packages and let's get going.

npm install @fortawesome/free-solid-svg-icons
Advertisement

Adding icons to the library

import { library } from '@fortawesome/fontawesome-svg-core'
import { fas } from '@fortawesome/free-solid-svg-icons'

library.add(fas)

The { library } import has an add() method which takes any number of arguments and registers icons for later use.

If we install another icon content package, this time the Free Brands:

npm install @fortawesome/free-brands-svg-icons

We can add this to the library at the same time as the Free Solid package.

import { library } from '@fortawesome/fontawesome-svg-core'
import { fas } from '@fortawesome/free-solid-svg-icons'
import { fab } from '@fortawesome/free-brands-svg-icons'

library.add(fas, fab)

Using the library

With icons in the library we can use the findIconDefinition() method to locate icon objects using their style prefix and their icon name.

import { findIconDefinition } from '@fortawesome/fontawesome-svg-core'

const glasses = findIconDefinition({ prefix: 'fas', iconName: 'glasses' })

What's going on here? The findIconDefinition() method is using the library to locate an icon that matches the prefix and iconName.

The Library enables all icon lookups

Without the Library any method of the API that needs to locate an icon would be unable to find it. The Library is a required piece of the puzzle and it's a good idea to become familiar with it if you are going to use the API.

The glasses object contains all the information about the icon–size, prefix, name, and the SVG path data. This is known as the icon definition.

{
  "prefix": "fas",
  "iconName": "glasses",
  "icon": [
    576,
    512,
    [],
    "f530",
    "M574.1 280.37L528.75 98.66c-5.91-23.7-21.59-44.05-43-55.81-21.44-11.73-46.97-14.11-70.19-6.33l-15.25 5.08c-8.39 2.79-12.92 11.86-10.12 20.24l5.06 15.18c2.79 8.38 11.85 12.91 20.23 10.12l13.18-4.39c10.87-3.62 23-3.57 33.16 1.73 10.29 5.37 17.57 14.56 20.37 25.82l38.46 153.82c-22.19-6.81-49.79-12.46-81.2-12.46-34.77 0-73.98 7.02-114.85 26.74h-73.18c-40.87-19.74-80.08-26.75-114.86-26.75-31.42 0-59.02 5.65-81.21 12.46l38.46-153.83c2.79-11.25 10.09-20.45 20.38-25.81 10.16-5.3 22.28-5.35 33.15-1.73l13.17 4.39c8.38 2.79 17.44-1.74 20.23-10.12l5.06-15.18c2.8-8.38-1.73-17.45-10.12-20.24l-15.25-5.08c-23.22-7.78-48.75-5.41-70.19 6.33-21.41 11.77-37.09 32.11-43 55.8L1.9 280.37A64.218 64.218 0 0 0 0 295.86v70.25C0 429.01 51.58 480 115.2 480h37.12c60.28 0 110.37-45.94 114.88-105.37l2.93-38.63h35.75l2.93 38.63C313.31 434.06 363.4 480 423.68 480h37.12c63.62 0 115.2-50.99 115.2-113.88v-70.25c0-5.23-.64-10.43-1.9-15.5zm-370.72 89.42c-1.97 25.91-24.4 46.21-51.06 46.21H115.2C86.97 416 64 393.62 64 366.11v-37.54c18.12-6.49 43.42-12.92 72.58-12.92 23.86 0 47.26 4.33 69.93 12.92l-3.13 41.22zM512 366.12c0 27.51-22.97 49.88-51.2 49.88h-37.12c-26.67 0-49.1-20.3-51.06-46.21l-3.13-41.22c22.67-8.59 46.08-12.92 69.95-12.92 29.12 0 54.43 6.44 72.55 12.93v37.54z"
  ]
}

One of the most useful API methods to use icon definitions with is icon(). It can transform an icon definition into an SVG representation suitable for use in the DOM or elsewhere.

import { findIconDefinition, icon } from '@fortawesome/fontawesome-svg-core'

const glasses = findIconDefinition({ prefix: 'fas', iconName: 'glasses' })
const i = icon(glasses)

// Loop through each node and appending it to the DOM body
Array.from(i.node).map(n => document.body.appendChild(n))
Advertisement

Subsetting

While it's easy to add entire styles to the library this results in some big files. A typical site, even one that uses a lot of icons, will only need a small portion of the thousands of icons Font Awesome provides.

That's where subsetting comes in.

Let's take our previous example and only import the icons that we need.

import { library } from '@fortawesome/fontawesome-svg-core'
import { faCamera } from '@fortawesome/free-solid-svg-icons'
import { faTwitter } from '@fortawesome/free-brands-svg-icons'

library.add(faCamera, faTwitter)

You can reap the benefits of this explicit import through bundling tools that eliminate "dead code". Dead code is anything in your final bundle that will never be used by your project (making it safe to be removed). This process is known as tree shaking. Rollup (opens new window) and Webpack 2+ (opens new window) are a couple of tools that support tree shaking (opens new window).