# FontAwesome

Add FontAwesome icons to your VuePress site. Fully compatible with all free and pro icons thanks to @fortawesome/vue-fontawesome (opens new window).

Out of the box the plugin only installs/registers the @fortawesome/vue-fontawesome components and the FontAwesome SVG core library. This gives you full flexibility over the icons you want to use, but requires a little setup upfront.

# Install SVG icons

First you need to install the icons you want to use. For example, let's use the free solid icons (opens new window).

yarn add -D @fortawesome/free-solid-svg-icons
# OR npm i -D @fortawesome/free-solid-svg-icons

# Import your icons

Now that the required SVG icons are installed they need to be registered with the FontAwesome SVG core library (to take advantage of only bundling the icons you actually use). For this, just create a file named fa-icons.js in your .vuepress folder and add the following code:

import { library } from '@fortawesome/fontawesome-svg-core'
import { faCoffee } from '@fortawesome/free-solid-svg-icons'

library.add(faCoffee)

This will import the :fas-coffee: icon and make it available in all your markdown files.

You can change the file that is used to import all of your icons with the iconsFile option.

# Markdown Shorthand

For quick access in markdown files this plugin adds a special :<prefix>-<icon>: syntax. For example to refer to the above coffee icon from the solid icons

This is the :fas-coffee: icon!

Example:

This is the :fas-coffee: icon!

# Vue Component

For more fine grained control over the displayed icon you can use the @fortawesome/vue-fontawesome components. For example, the basic <font-awesome-icon /> component can be used to display the icon and pass additional options:

<font-awesome-icon :icon="['fas', 'coffee']" size="4x" />

Example:

See the supported features (opens new window) of @fortawesome/vue-fontawesome for a list of all available compoents and options. All three components are already registered as global components so you can use all basic and advanced features.