tailwind-fontawesome

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'
        }
    }
};

Changelog

0.7.1 (2024-07-14)

Fixes

• fix missing colon in plugin config (f98fd1b)