Check out the all-new Web Awesome AND get an exclusive lifetime discount on Font Awesome!

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().

For additional information, visit [styles] and [aliases] to see how they can be used within findIconDefinition().

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="fas" 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': 'fas',
      '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'
        }
      }
    ]
  }
]

// The `data-prefix` attribute will only accept short prefix names (ex. fas, far, fal, fat, fad, fass)

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="fas"
  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="fas"
  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="fas"
  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' })

parse.icon(icon)

Takes an icon string, an object, or an array and returns an icon definition.

What is it?

The parse.icon() method will allow the user to input an icon’s name (or alias) as a string, an object, or an array when calling an icon. See our Vue docs for an example.

The parse.icon() method also normalizes our styles and icon names. For example, you can reference our solid icons with with a prefix of 'solid', 'fa-solid', 'fas', or 'fa'.

Additionally, you can reference our icons with just the icon name, which will default to solid style.

How to Use

Referencing the icon as a string:

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

// the icon's style will default to Solid, it's family will default to Classic
parse.icon('dog')

// returns an object, with the default `fas` prefix
// {prefix: 'fas', iconName: 'dog'}

Referencing the icon as an object with a short prefix name:

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

// No additional parsing was needed for this since it started with the prefix and icon name
parse.icon({ prefix: 'fas', iconName: 'dog' }) // {prefix: 'fas', iconName: 'dog'}

// Same deal, no additional parsing is required for the Sharp family either
parse.icon({ prefix: 'fass', iconName: 'cat' }) // {prefix: 'fass', iconName: 'cat'}

Referencing the icon as an object with a long prefix name:

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

// a classic solid dog icon
parse.icon({ prefix: 'fa-solid', iconName: 'dog' }) // { prefix: 'fas', iconName: 'dog' }

Referencing the icon as an array with non-prefix:

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

// This only lets you select the Classic family:
parse.icon(['solid', 'dog'])

Prefixes and Style Classes

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

Style	Style Class
Brand	`"fab"`, `"fa-brands"`
Solid	`"fa"`, `"fas"`, `"fa-solid"`
Regular	`"far"`, `"fa-regular"`
Light	`"fal"`, `"fa-light"`
Thin	`"fat"`, `"fa-thin"`
Duotone	`"fad"`, `"fa-duotone"`
Sharp Solid	`"fass"`, `"fa-sharp fa-solid"`

Read more about our basic styling or how aliases 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.