tailwind-fontawesome

A set of utility classes that make pairing Font Awesome with Tailwind CSS a breeze 💨.

Before you start

Before you can use this plugin, you still need to separately include the Font Awesome library in your project.

The quickest way to get started is via the official CDN with a free Font Awesome kit via the website. Other methods are available as well.

Support

This plugin is currently compatible with both Tailwind 2 & 3. From the 1.0.0 release onwards, only Tailwind 3 will be supported. Previous releases should continue to work for the foreseeable future however.

Installation

Install the plugin:

# Using NPM
npm install tailwind-fontawesome

# Using Yarn
yarn add tailwind-fontawesome

# Using PNPM
pnpm install tailwind-fontawesome

Then add the plugin to your tailwind.config.js file:

// tailwind.config.js
module.exports = {
    theme: {
        // ...
    },
    plugins: [
        require('tailwind-fontawesome')
        // ...
    ]
};

Need the Pro version?

By default, the plugin will reference the free Font Family. If you have a Font Awesome Pro kit, you can switch the Font Family by passing the following configuration option:

// tailwind.config.js
module.exports = {
    theme: {
        // ...
    },
    plugins: [
        require('tailwind-fontawesome')({
            pro: true
        })
        // ...
    ]
};

What about Font Awesome 6?

The plugin defaults to Font Awesome 5, however, from version 0.3 Font Awesome 6 icon sets are also supported:

// tailwind.config.js
module.exports = {
    theme: {
        // ...
    },
    plugins: [
        require('tailwind-fontawesome')({
            version: 6
        })
        // ...
    ]
};

Classic vs Sharp?

The newer 'sharp' icon sets are supported via the family option (v0.4 and up), otherwise 'classic' mode is assumed:

// tailwind.config.js
module.exports = {
    theme: {
        // ...
    },
    plugins: [
        require('tailwind-fontawesome')({
            family: 'sharp'
        })
        // ...
    ]
};

In the above use case, the pro and version options may be omitted (Sharp sets are only available in Font Awesome 6 Pro).

Custom Mapping

If you want to have a custom mapping or add missing icons you can use the custom option (v0.6 and up):

// tailwind.config.js
module.exports = {
    theme: {
        // ...
    },
    plugins: [
        require('tailwind-fontawesome')({
            custom: [{ name: 'x-twitter', code: 'e61b' }]
        })
        // ...
    ]
};

Usage

At it's simplest, combine a positional class (e.g. icon-before) and an icon class (e.g. icon-{name}) to display an icon in the target element - {name} refers to the icon name in dash case as listed on the official website:

<button class="icon-before icon-chevron-right">
    <!-- Label -->
</button>

Use icon-space-{size} to adjust the gap between the icon and other content:

<button class="icon-before icon-chevron-right icon-space-sm">
    <!-- Label -->
</button>

Placement

| Class | Behavior | | -------------- | :----------------------------------------------------------------------------------- | | icon-before | Place icon at the start of content using ::before | | icon-after | Place icon at the end of an content using ::after | | icon-outside | Place icon outside the left-hand margin, useful for bulleting the first line of text | | icon-inline | Used when directly referencing an icon with Unicode in your markup (e.g. &#xf268) |

Styles

| Class | Weight | Font Family | | ---------------- | ------ | :-------------------------------------------------------- | | icon-thin | 100 | "Font Awesome 6 Pro" only | | icon-light | 300 | "Font Awesome {5/6} Pro" | | icon-regular | 400 | "Font Awesome {5/6} Pro" | | icon-solid | 900 | "Font Awesome {5/6} Free" or "Font Awesome {5/6} Pro" | | icon-duotone* | 900 | "Font Awesome {5/6} Duotone" | | icon-brands | 900 | "Font Awesome {5/6} Brands" |

* Not fully supported, yet

Spacing

| Class | Margin | | ---------------- | --------- | | icon-space-xs | 0.25rem | | icon-space-sm | 0.5rem | | icon-space-md | 0.75rem | | icon-space-lg | 1rem | | icon-space-xl | 1.25rem | | icon-space-2xl | 1.5rem | | icon-space-3xl | 1.75rem |

Vertical Alignment

This plugin defaults to 'middle' for icon alignment but sometimes this is not the best approach, as in the case of uppercase text. Use the below utilities to override that behaviour.

| Class | Vertical Alignment | | --------------- | ------------------ | | icon-baseline | baseline | | icon-sub | sub | | icon-super | super | | icon-top | top | | icon-middle | middle | | icon-bottom | bottom |

Icons

| Class | Unicode | | -------------------- | ------- | | icon-chevron-right | f054 | | icon-paper-plane | f1d8 | | ... | ... |

Full list of available icons at the Font Awesome website

Customization

You can override/extend the generated style and spacing values in your tailwind.config.js file:

// tailwind.config.js
module.exports = {
    theme: {
        iconStyle: {
            thin: '100',
            light: '300',
            regular: '400',
            solid: '900'
            // Brands and Duotone are reserved and can't be overridden
        },
        iconSpacing: {
            xs: '0.25rem',
            sm: '0.5rem',
            md: '0.75rem',
            lg: '1rem',
            xl: '1.25rem',
            '2xl': '1.5rem',
            '3xl': '1.75rem'
        }
    }
};