Skip to content

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
})
NamePurpose
autoReplaceSvgRootlimits the scope for automatic search and replacement of icons.
observeMutationsRootlimits 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:

StyleStyle Class
Brandfab, brands
Duotonefad, duotone
Lightfal,light
Regularfar, regular
Solidfa, 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

VerbWhat it does
growMakes the icon larger
shrinkMakes the icon smaller
leftMove the icon to the left
rightMove the icon to the right
upMove the icon up
downMove the icon down
rotateRotate the icon left or right
flip-vFlips along the vertical axis
flip-hFlips 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.