APIs

Methods

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

Advertisement

Before You Get Started

Make sure you already:

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 (opens new window) 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 })
Advertisement

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.

Different default configs

DOM watching is on by default when Font Awesome is loaded from @fortawesome/fontawesome-free or @fortawesome/fontawesome-pro but it's disabled for the @fortawesome/fontawesome-svg-core.

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

Did You Know?!

Aliases and the various styles syntax can be used within findIconDefinition().

Advertisement

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 (opens new window):

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"
        }
      }
    ]
  }
]

"Marty, you're not thinking fourth-dimensionally!"

The abstract value is mostly useful for library / framework / tooling creators. It provides a data structure that can easily be converted into other objects.

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

More than meets the eye...

If you need help figuring out transforms, see parse.transform.

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
Advertisement

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'})
Advertisement

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 class and style will default to "solid"
parse.icon('dog')

// returns an object, with a default class of `solid` or `fas`
// {prefix: 'fas', iconName: 'dog'}

The above code is the same as doing the following:

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

// the icon's class and style is set to "solid"
parse.icon({ prefix: 'fas', iconName: 'dog'})

// returns an object, with a class of `solid` or `fas`
// {prefix: 'fas', iconName: 'dog'}

Referencing the icon as an object with style of 'fa-solid':

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

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

Referencing the icon as an array with style of 'solid':

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

parse.icon(['solid', 'dog'])

Default Style

When calling the icons, if a style (solid, thin, duotone, etc.) is not specified or there is not a styleDefault set, the icon's class and style will default to solid.

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, fa-brands, brands
Duotone fad, fa-duotone, duotone
Light fal, fa-light, light
Regular far, fa-regular, regular
Solid fa, fas, fa-solid, solid
Thin fat, fa-thin, thin

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

Advertisement

parse.transform(transformString)

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

Up, Up, Down, Down, Left, Right, Left, Right, B, A

This is an internal method that you probably won't need but it might be useful to know how the translation happens.

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
}
Advertisement

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.

Advertisement