# Icon Library

Documentation for managing and accessing Font Awesome icons via the JavaScript icon library API.

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

## Font Awesome SVG Core and icon content packages

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

```bash
npm install @fortawesome/fontawesome-svg-core
```

We'll be using the [`library` object](/apis/javascript/methods.md#library-add-icondefinitions) which is part of the API. Install one of the **icon content** packages and let's get going.

  **Kit Package:**
  **Pro SVG Icon Package:**
  **Free SVG Icon Package:**

```bash
npm i --save '@awesome.me/kit-KIT_CODE'
```

```bash
# Pro icons styles
npm i --save @fortawesome/pro-solid-svg-icons
npm i --save @fortawesome/pro-regular-svg-icons
npm i --save @fortawesome/pro-light-svg-icons
npm i --save @fortawesome/pro-thin-svg-icons
npm i --save @fortawesome/pro-duotone-svg-icons
npm i --save @fortawesome/duotone-regular-svg-icons
npm i --save @fortawesome/duotone-light-svg-icons
npm i --save @fortawesome/duotone-thin-svg-icons
npm i --save @fortawesome/sharp-solid-svg-icons
npm i --save @fortawesome/sharp-regular-svg-icons
npm i --save @fortawesome/sharp-light-svg-icons
npm i --save @fortawesome/sharp-thin-svg-icons
npm i --save @fortawesome/sharp-duotone-solid-svg-icons
npm i --save @fortawesome/sharp-duotone-regular-svg-icons
npm i --save @fortawesome/sharp-duotone-light-svg-icons
npm i --save @fortawesome/sharp-duotone-thin-svg-icons
```

```bash
# Free icons styles
npm install @fortawesome/free-solid-svg-icons
npm i --save @fortawesome/free-regular-svg-icons
npm i --save @fortawesome/free-brands-svg-icons
```

## Adding icons to the library

  **Kit Package:**
  **Pro:**
  **Free:**

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

library.add(...all)
```

```js
import { library } from '@fortawesome/fontawesome-svg-core'
import { fas } from '@fortawesome/pro-solid-svg-icons'
import { far } from '@fortawesome/pro-regular-svg-icons'
import { fal } from '@fortawesome/pro-light-svg-icons'
import { fat } from '@fortawesome/pro-thin-svg-icons'
import { fad } from '@fortawesome/pro-duotone-svg-icons'
import { fass } from '@fortawesome/sharp-solid-svg-icons'
import { fasr } from '@fortawesome/sharp-regular-svg-icons'
import { fasl } from '@fortawesome/sharp-light-svg-icons'
import { fast } from '@fortawesome/sharp-thin-svg-icons'
import { fasds } from '@fortawesome/sharp-duotone-solid-svg-icons'

library.add(fas, far, fal, fat, fad, fass, fasr, fasl, fast, fasds)
```

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

library.add(fas, far, fab)
```

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

## 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.

```js
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`.

  <h4>
   The Library enables all icon lookups
  </h4>
  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**.

```js
{
  "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()`](/apis/javascript/methods.md#icon-icondefinition-params). It can transform an **icon definition** into an SVG representation suitable for use in the DOM or elsewhere.

```js
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))
```

## 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.

```js
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](https://rollupjs.org) and [Webpack 2+](https://webpack.js.org) are a couple of tools that support [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking).