Say hello to Web Awesome, the biggest and best library of open-source web components.

Methods

Below are the methods available in the Font Awesome Javascript API.

counter(content, params)

Add counters to layers.

import { faEnvelopeSquare } from '@fortawesome/free-solid-svg-icons'
import { layer, icon, counter } from '@fortawesome/fontawesome-svg-core'
layer((push) => {
  push(icon(faEnvelopeSquare))
  push(counter("5"))
}).html

Params

Allow the following keys (see icon()):

Name
`title`
`classes`
`attributes`
`styles`

dom.css()

Stylesheet definitions required to properly display icons generated by the API in the DOM.

Generates the accompanying CSS that is necessary to correctly display icons. If you choose to disable autoAddCss in the configuration you’ll need to grab these styles and insert them manually into the DOM.

This is useful and normally paired with dom.insertCss().

dom.i2svg(params)

Will automatically find any <i> tags in the page and replace those with <svg> elements.

This functionality uses requestAnimationFrame to batch the updates and increase performance.

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

library.add(fas)

dom.i2svg()

To specify a different element to search:

dom.i2svg({ node: document.getElementById('content') })

As of version 5.7.0, this method also supports the Promise API:

dom.i2svg()
  .then(function () {
    console.log('Icons have rendered')
  })

You can also use callbacks that will be triggered when the icons have been rendered:

function iconDoneRendering () {
  console.log('Icons have rendered')
}

dom.i2svg({ callback: iconsDoneRendering })

dom.insertCss()

Convenience method that will add the given CSS to the DOM <head>.

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

const css = dom.css()

dom.insertCss(css)

dom.watch(params)

Calls dom.i2svg() for you and watches the DOM for any additional icons being added or modified.

This method is useful when you’re loading @fortawesome/fontawesome-svg-core, but would still like to leverage automatic DOM watching.

Params

Calling dom.watch() without params is equivalent to calling with the following params:

dom.watch({
  autoReplaceSvgRoot: document,
  observeMutationsRoot: document
})

Name	Purpose
`autoReplaceSvgRoot`	limits the scope for automatic search and replacement of icons.
`observeMutationsRoot`	limits the scope of the mutation observer to the DOM under this root node.

findIconDefinition(params)

Look up an icon definition previously registered in the Library.

Basic Use

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

const faUser = findIconDefinition({iconName: 'user'})

{
  "prefix": "fas",
  "iconName": "user",
  "icon": [
    512,
    512,
    [],
    "f007",
    "M962…-112z"
  ]
}

Specify the prefix as well

findIconDefinition({prefix: 'fab', iconName: 'fort-awesome'})

{
  "prefix": "fab",
  "iconName": "fort-awesome",
  "icon": [
    448,
    512,
    [],
    "f286",
    "M412…999z"
  ]
}

You can then feed this as the iconDefinition to other functions such as icon().

icon(iconDefinition, params)

Renders an icon as SVG.

Basic Use

import { icon } from '@fortawesome/fontawesome-svg-core'
import { faPlus } from '@fortawesome/free-solid-svg-icons'

const faPlusIcon = icon(faPlus)

Advanced Options

Getting the HTML for the icon:

icon(faPlus).html

[
  '<svg data-prefix="fa" data-icon="user" class="svg-inline--fa fa-user fa-w-16">...</svg>'
]

Appending nodes from an HTMLCollection:

const faPlusIcon = icon(faPlus)

// Get the first element out of the HTMLCollection
document.appendChild(faPlusIcon.node[0])

Abstract tree:

icon(faPlus).abstract

[
  {
    "tag": "svg",
    "attributes": {
      "data-prefix": "fa",
      "data-icon": "user",
      "class": "svg-inline--fa fa-user fa-w-16",
      "role": "img",
      "xmlns": "http://www.w3.org/2000/svg",
      "viewBox": "0 0 512 512"
    },
    "children": [
      {
        "tag": "path",
        "attributes": {
          "fill": "currentColor",
          "d": "M96…112z"
        }
      }
    ]
  }
]

Using a transform:

icon(faPlus, {
  transform: {
    size: 8,     // starts at 16 so make it half
    x: -4,       // the same as left-4
    y: 6,        // the same as up-6
    rotate: 90,  // the same as rotate-90
    flipX: true, // the same as flip-h
    flipY: true  // the same as flip-v
  }
}).html

Use the main icon as a mask for another another icon:

import { icon } from '@fortawesome/fontawesome-svg-core'
import { faPlus, faCircle } from '@fortawesome/free-solid-svg-icons'

icon(faPlus, {
  mask: faCircle
}).html

Specify mask ID used to generate the SVG definitions (added in 5.12.2):

This is useful for testing libraries that use snapshots to verify test results.

import { icon } from '@fortawesome/fontawesome-svg-core'
import { faPlus, faCircle } from '@fortawesome/free-solid-svg-icons'

icon(faPlus, {
  mask: faCircle,
  maskId: 'circle'
}).html

Add title attribute:

icon(faBars, {
  title: 'Navigation menu'
}).html

[
  '<svg aria-labelledby="svg-inline--fa-title-abuUI77dy8" data-prefix="fa" data-icon="bars" class="svg-inline--fa fa-bars fa-w-14" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512" >' +
    '<title id="svg-inline--fa-title-abuUI77dy8">Navigation menu</title>' +
    '<path></path>' +'</svg>'
]

Explicit title ID when add title (added in 5.12.2):

This is useful for testing libraries that use snapshots to verify test results.

icon(faBars, {
  title: 'Navigation menu',
  titleId: 'navigation-menu'
}).html

[
  '<svg aria-labelledby="svg-inline--fa-title-navigation-menu" data-prefix="fa" data-icon="bars" class="svg-inline--fa fa-bars fa-w-14" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512" >' +
    '<title id="svg-inline--fa-title-navigation-menu">Navigation menu</title>' +
    '<path></path>' + '</svg>'
]

Additional classes:

icon(faSpinner, {
  classes: ['fa-spin']
}).html

[
  '<svg data-prefix="fa" data-icon="spinner" class="svg-inline--fa fa-spinner fa-w-16 fa-spin">…</svg>'
]

Additional attributes:

icon(faSpinner, {
  attributes: { 'data-component-id': 987654 }
}).html

Additional styles:

icon(faSpinner, {
  styles: { 'background-color': 'coral' }
}).html

Creating a symbol (auto-generating ID):

icon(faSpinner, {
  symbol: true
}).html

Creating a symbol (explicit ID):

icon(faSpinner, {
  symbol: 'spinner-icon'
}).html

layer(assembler, params)

Allows multiple icons to be assembled together in a layer.

Convenience function for producing the HTML markup for layers. It wraps icon(), text(), or counter() inputs in <span class="fa-layers fa-fw"></span>.

import { faSpinner } from '@fortawesome/free-solid-svg-icons'
import { layer, icon } from '@fortawesome/fontawesome-svg-core'

layer((push) => {
  push(icon(faSpinner))
  push(icon(faUser, { transform: { size: 4 } } ))
}).html

Specify additional classes like this.

import { faSpinner } from '@fortawesome/free-solid-svg-icons'
import { layer, icon } from '@fortawesome/fontawesome-svg-core'

layer((push) => {
  push(icon(faSpinner))
  push(icon(faUser, { transform: { size: 4 } } ))
}, { classes: ['sign-in-loading'] }).html

Params

Allow the following keys:

Name
`classes`

library.add(…iconDefinitions)

Pre-registering icon definitions so that do not have to explicitly pass them to render an icon.

Explicitly passing the icon

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

icon(faUser)
icon(fab.faFortAwesome)

Using the library

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

library.add(fab, faUser)

icon({prefix: 'fas', iconName: 'user'})
icon({prefix: 'fab', iconName: 'fort-awesome'})

Prefixes and Style Classes

Like the number of our icons, our styles have grown too! We now have icons in six styles. The chart below outlines all of our styles along with how you can use them with Font Awesome Icons:

Style	Style Class
Brand	`fab`, `brands`
Duotone	`fad`, `duotone`
Light	`fal`,`light`
Regular	`far`, `regular`
Solid	`fa`, `fas`, `solid`

Read more about our basic styling can be used in conjunction with the styling.

parse.transform(transformString)

Takes a Power Transform string and produces the normalized transform object used by the API.

Power Transforms are space-separated verbs and values.

Transform verbs

Verb	What it does
grow	Makes the icon larger
shrink	Makes the icon smaller
left	Move the icon to the left
right	Move the icon to the right
up	Move the icon up
down	Move the icon down
rotate	Rotate the icon left or right
flip-v	Flips along the vertical axis
flip-h	Flips along the horizontal axis

Transform Values

Font Awesome 5 icons are built on a sixteen pixel grid. For size and movement values represent 1 unit out of 16.

For example, up-2 means “move the icon up 2 units”. If the icon happens to be 16px high this will result in the icon being moved up by 2 pixels.

Converting to SVG transform values

Power Transform string are easy to use and compose but must be converted into a format that is useful to perform SVG transforms.

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

parse.transform('grow-2 left-4 rotate-15')

The following data is what gets used when rendering icons.

{
  "size": 18,
  "x": -4,
  "y": 0,
  "flipX": false,
  "flipY": false,
  "rotate": 15
}

text(content, params)

Add text to layers.

import { faSpinner } from '@fortawesome/free-solid-svg-icons'
import { layer, icon, text } from '@fortawesome/fontawesome-svg-core'

layer((push) => {
  push(icon(faSpinner))
  push(text('Wait…', { transform: { size: 4 } } ))
}).html

Params

Allow the following keys (see icon()):

Name
`transform`
`title`
`classes`
`attributes`
`styles`

toHtml(abstractElement)

Convenience method to convert an abstract representation of a Font Awesome object into its corresponding HTML markup.

The icon(), text(), layer(), and counter() functions each return a Font Awesome object that has properties abstract and html. (See also the documentation for icon() more details about the shape of such objects.)

toHtml() can be used to transform any abstract element into HTML.