Add Icons with Vue

There are a few ways of adding icons to a Vue project. Choose the option that works for your project, and then get those icons into your UI!

Before You Get Started

Make sure you:

• Completed the steps to Set up with Vue

About Adding Icons in Vue

There are a bunch of ways to add icons in a Vue project. Which one is right for you depends on how you set up your project and how you plan to use icons. Here is a quick overview of the options — the details on how to use each are below.

Check Your Icon Import and Usage Syntax

Ensure that you’re both importing and using the icon in the correct format. Icon names need to follow a specific naming convention based on how they are imported and then ultimately used. Check the examples in the appropriate section to verify the correct import syntax and usage.

Type	Method	Pros	Cons
Kit Pkg Best Pro Option	ByPrefixAndName	Easiest, and lightweight when you subset your Kit	Not centralized, can be bulky if you don’t subset your Kit
Kit Pkg	Individual Icons	Easy to see which icons are imported, Allows tree-shaking	Not centralized, tedious to add many icons, can be ambiguous about style
Kit Pkg	Whole Styles	Fast way to add lots of icons	Not centralized, bulky
Kit Pkg	Use the Library	Import all the icons in your Kit once, use anywhere in your Vue project	Can be bulky if you don’t subset your Kit
SVG Pkg	Individual Icons	Easy to see which icons are imported	Tedious to add many icons, can be ambiguous about style
SVG Pkg Best Free Option	Whole Styles (Free)	Easy way to add all the Free icons	Only includes Free icons
SVG Pkg	Whole Styles	Fast way to add lots of icons	Can be very bulky, doesn’t work with tree-shaking

Add Icons Using a Kit Package

The easiest way to add icons when using Vue is with a Pro Kit package — which lets you add your own custom icons and create a custom subset with just the icons or styles you need. Check out the Kit Package API docs to find out what’s in the package and learn more about using one.

Use a Kit Package for Pro+ and Custom Icons

Pro Kits are the only way to use Pro+ Icons and Custom Icons in a package — they are not available in any other packages.

And don’t forget - for the examples below to work, you’ll need to make sure your Kit contains the icons in the examples, especially if you’ve subsetted your Kit. If you’re not familiar with how Kits work, you can learn more about Kits.

By Prefix and Name

This is the juuuust right way to add icons in Vue - not too much importing or configuring, just straight to the icons. Here’s an example of it (using shorthand prefix to specify family and style) in practice:

<script setup>
  import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
  import { byPrefixAndName } from '@awesome.me/kit-KIT_CODE/icons'
</script>

<template>
  <!-- Font Awesome Classic Solid (fas) icon -->
  <FontAwesomeIcon :icon="byPrefixAndName.fas['house']" />

  <!-- Font Awesome Classic Regular (far) icon -->
  <FontAwesomeIcon :icon="byPrefixAndName.far['circle-user']" />

  <!-- Custom icon -->
  <FontAwesomeIcon :icon="byPrefixAndName.fak['my-icon']" />
</template>

Importing Specific Icons

An alternative to using the shorthand prefix and name is by importing icons directly. This is your best bet at leveraging tree-shaking if that’s useful to you. We still recommend preserving the shorthand prefix in your import names if you’re using an icon in multiple styles.

<script setup>
  import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
  import { faHouse } from '@awesome.me/kit-KIT_CODE/icons/classic/solid'
  import { faCircleUser } from '@awesome.me/kit-KIT_CODE/icons/classic/regular'
  import { faTree, faDragon as fassFaDragon  } from '@awesome.me/kit-KIT_CODE/icons/sharp/solid'
  import { faDog } from '@awesome.me/kit-KIT_CODE/icons/duotone/solid'
  import { faDragon as fasdsFaDragon } from '@awesome.me/kit-KIT_CODE/icons/sharp-duotone/solid'
  import { faMyIcon } from '@awesome.me/kit-KIT_CODE/icons/kit/custom'
</script>

<template>
  <!-- Font Awesome icons -->
  <FontAwesomeIcon :icon="faHouse" />
  <FontAwesomeIcon :icon="faCircleUser" />
  <FontAwesomeIcon :icon="faTree" />
  <FontAwesomeIcon :icon="faDog" />

  <!-- Font Awesome icon in multiple styles (with shorthand prefixes included) -->
  <FontAwesomeIcon :icon="fassFaDragon" />
  <FontAwesomeIcon :icon="fasdsFaDragon" />

  <!-- Custom icon -->
  <FontAwesomeIcon :icon="faMyIcon" />
</template>

Importing Whole Styles

You can use all the icons in a style by importing each’s shorthand prefix, but this method won’t work with tree-shaking and can add bloat to your project since it includes all the icons in the style so use it only when the other methods don’t work for your project.

<script setup>
  import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
  import { fas, far, fad, fass, fasds, fak } from '@awesome.me/kit-KIT_CODE/icons'
</script>

<template>
  <!-- Font Awesome icons -->
  <FontAwesomeIcon :icon="fas.faHouse" />
  <FontAwesomeIcon :icon="far.faCircleUser" />
  <FontAwesomeIcon :icon="fad.faMouse" />
  <FontAwesomeIcon :icon="fass.faCat" />
  <FontAwesomeIcon :icon="fasds.faDog" />

  <!-- Custom icons -->
  <FontAwesomeIcon :icon="fak.faMyIcon" />
  <FontAwesomeIcon :icon="fak.faAnotherOne" />
  <FontAwesomeIcon :icon="fak.faMyLogo" />
</template>

Using the Library

Another mechanism that the Font Awesome Core provides is a JavaScript class called Library. With a subsetted Kit, this can be an easy way to add all icons once and use them with a syntax that requires less typing.

First set up the Library:

// in main.ts or main.js
import './assets/main.css'

import { createApp } from 'vue'
import { createPinia } from 'pinia'

import App from './App.vue'
import router from './router'

/* import the fontawesome core */
import { library } from '@fortawesome/fontawesome-svg-core'

/* import font awesome icon component */
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'

/* import specific icons */
import { all } from '@awesome.me/kit-KIT_CODE/icons'

/* add icons to the library */
library.add(...all)

const app = createApp(App)

app.component('font-awesome-icon', FontAwesomeIcon)
app.use(createPinia())
app.use(router)

app.mount('#app')

Now all icons in the Kit have been added in just one, easy line. No fuss, no muss. But you’ll want to make sure your Kit is using subsetting so you aren’t loading tons of icons you’re not using.

A nice benefit of this method is that you can just add the icon as an array (using the shorthand prefix for your desired style) or string in your templates without having to import the icons individually.

Also note here that we’ve switched from importing and using FontAwesomeIcon directly. Instead, we are using the already registered component through app.component(). When you use the Library this way, you’ll use a slightly different syntax and the lower case, hyphenated <font-awesome-icon ...> instead of camelCase.

As a string

<template>
  <font-awesome-icon icon="fa-solid fa-house" />
  <font-awesome-icon icon="fa-regular fa-circle-user" />
</template>

As an array

<template>
  <font-awesome-icon :icon="['fas', 'house']" />
  <font-awesome-icon :icon="['far', 'circle-user']" />
</template>

Custom icons are just as easy.

As a string

<template>
  <font-awesome-icon icon="fa-kit fa-my-icon" />
</template>

As an array

<template>
  <font-awesome-icon :icon="['fak', 'my-icon']" />
</template>

Add Icons Using SVG Icon Packages

If you can’t or don’t want to use a Kit, you can add icons into your Vue project components using our SVG packages by style. (Remember: Pro+ and Custom icons aren’t available with SVG Packages - you’ll need to use a Kit package to use those icons.)

Follow these steps to get set up…

Set up the Library

You’ll first create a library of all the icons you want to use in your project in the src/main.js or src/main.ts file. Here’s an example that adds the User Secret and Thumbs Up icons in Solid style and the Facebook Brand icon to the library:

import { createApp } from 'vue'
import App from './App.vue'

/* import the fontawesome core */
import { library } from '@fortawesome/fontawesome-svg-core'

/* import font awesome icon component */
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'

/* import icons and add them to the Library */
import { faUserSecret, faThumbsUp } from '@fortawesome/free-solid-svg-icons'
import { faFacebook } from '@fortawesome/free-brands-svg-icons'

library.add(faUserSecret, faThumbsUp, faFacebook)

createApp(App)
.component('font-awesome-icon', FontAwesomeIcon)
.mount('#app')

Add Individual Icons

You can now call the icons, using either a string format or an array format. Just use the syntax below wherever you want the icons to appear in your project, like in the src/App.vue file. Below is the rest of the example we started above that adds the icons into the app UI.

Also note here that we’ve switched from importing and using FontAwesomeIcon directly and are using the already registered component, through app.component(). When you use the Library, you’ll use a slightly different syntax and the lower case, hyphenated <font-awesome-icon ...> instead of camelCase.

As a string

<template>
  <div id="app">
    <!-- Add the style and icon you want using the String format -->
    <font-awesome-icon icon="fa-solid fa-user-secret" />
    <font-awesome-icon icon="fa-solid fa-thumbs-up" />
    <font-awesome-icon icon="fa-brands fa-facebook" />
  </div>
</template>

<script>
  export default {
    name: 'App'
  }
</script>

As an array

<template>
  <div id="app">
    <!-- Add the style and icon you want using the Array format -->
    <font-awesome-icon :icon="['fas', 'user-secret']" />
    <font-awesome-icon :icon="['fas', 'thumbs-up']" />
    <font-awesome-icon :icon="['fab', 'facebook']" />
  </div>
</template>

<script>
  export default {
    name: 'App'
  }
</script>

Same Icon, Different Styles

Using ES modules and import statements we can define unique names for two or more different styles of the same icon (using shorthand prefix to specify each style). Here’s an example with different styles of the “house” icon:

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

import { faHouse as fasFaHouse } from '@fortawesome/pro-solid-svg-icons'
import { faHouse as fadFaHouse } from '@fortawesome/pro-duotone-svg-icons'
import { faHouse as fadtFaHouse } from '@fortawesome/duotone-thin-svg-icons'
import { faHouse as fassFaHouse } from '@fortawesome/sharp-solid-svg-icons'
import { faHouse as fasdsFaHouse } from '@fortawesome/sharp-duotone-solid-svg-icons'
import { faCircleUser as farFaCircleUser } from '@fortawesome/pro-regular-svg-icons'
import { faCircleUser as falFaCircleUser } from '@fortawesome/pro-light-svg-icons'

library.add(fasFaHouse, fadFaHouse, fadtFaHouse, fassFaHouse, fasdsFaHouse, farFaCircleUser, falFaCircleUser)

And here’s how you would add the “house” icon in various styles into your component:

As a string

<font-awesome-icon icon="fa-solid fa-house" />
<font-awesome-icon icon="fa-duotone fa-solid fa-house" />
<font-awesome-icon icon="fa-duotone fa-thin fa-house" />
<font-awesome-icon icon="fa-sharp fa-solid fa-house" />
<font-awesome-icon icon="fa-sharp-duotone fa-solid fa-house" />
<font-awesome-icon icon="fa-regular fa-circle-user" />
<font-awesome-icon icon="fa-light fa-circle-user" />

As an array

<font-awesome-icon :icon="['fas', 'house']" />
<font-awesome-icon :icon="['fad', 'house']" />
<font-awesome-icon :icon="['fadt', 'house']" />
<font-awesome-icon :icon="['fass', 'house']" />
<font-awesome-icon :icon="['fasds', 'house']" />
<font-awesome-icon :icon="['far', 'circle-user']" />
<font-awesome-icon :icon="['fal', 'circle-user']" />

Add Whole Styles

Free only

If you’re just using the Free icons, the easiest way to get the icons into your app is to add the Free SVG Icon Packages. Here’s an example of how to do that:

/* add fontawesome core */
import { library } from '@fortawesome/fontawesome-svg-core'

/* import all the icons in Free Solid, Free Regular, and Brands styles */
import { fas } from '@fortawesome/free-solid-svg-icons'
import { far } from '@fortawesome/free-regular-svg-icons'
import { fab } from '@fortawesome/free-brands-svg-icons'

library.add(fas, far, fab)

And then you can use any of the icons in those styles without having to explictly import them, like this:

As a string

<template>
  <font-awesome-icon icon="fa-solid fa-dog" />
  <font-awesome-icon icon="fa-regular fa-circle-user" />
  <font-awesome-icon icon="fa-brands fa-threads" />
<template>

As an array

<template>
  <font-awesome-icon :icon="['fas', 'dog']" />
  <font-awesome-icon :icon="['far', 'circle-user']" />
  <font-awesome-icon :icon="['fab', 'threads']" />
</template>

Add Whole Pro Styles

You can also add all the icons in a style - like Sharp Regular or Duotone - but be careful as each Pro style has thousands of icons. Here’s an example of how to import whole styles (using shorthand prefix to specify each style):

/* add fontawesome core */
import { library } from '@fortawesome/fontawesome-svg-core'

/* import all the icons in Free Solid, Duotone Solid, and Duotone Thin styles */
import { fas } from '@fortawesome/free-solid-svg-icons'
import { fad } from '@fortawesome/pro-duotone-svg-icons'
import { fadt } from '@fortawesome/duotone-thin-svg-icons'

library.add(fas, fad, fadt)

And then you can use any of the icons in those styles without having to explictly import them, like this:

As a string

<template>
  <font-awesome-icon icon="fa-solid fa-dog" />
  <font-awesome-icon icon="fa-duotone fa-solid fa-circle-user" />
  <font-awesome-icon icon="fa-duotone fa-thin fa-fish" />
<template>

As an array

<template>
  <font-awesome-icon :icon="['fas', 'dog']" />
  <font-awesome-icon :icon="['fad', 'circle-user']" />
  <font-awesome-icon :icon="['fadt', 'fish']" />
</template>

A Longer Example with Several Styles and Icons

Here’s an example with a number of icons in different styles, just to give you a sense of how the syntax changes from style to style in your main.js file.

/* add fontawesome core */
import { library } from '@fortawesome/fontawesome-svg-core'

/* these imports add ALL the icons in the style/package */
import { fas } from '@fortawesome/free-solid-svg-icons'
import { fad } from '@fortawesome/pro-duotone-svg-icons'
import { fadt } from '@fortawesome/duotone-thin-svg-icons'
import { fass } from '@fortawesome/sharp-solid-svg-icons'
import { fasds } from '@fortawesome/sharp-duotone-solid-svg-icons'

/* these imports add only the icons named */
import { faThreads, faFontAwesome } from '@fortawesome/free-brands-svg-icons'
import { faHatCowboy } from '@fortawesome/duotone-light-svg-icons'
import { faHatChef } from '@fortawesome/sharp-thin-svg-icons'

library.add(fas, fass, fad, fadt, fasds, faThreads, faFontAwesome, faHatCowboy, faHatChef)

In our call to library.add() we’re passing:

• fas: style shorthand that represents all of the icons in @fortawesome/free-solid-svg-icons *
• fad: style shorthand that represents all the Duotone Solid icons in @pro-duotone-svg-icons *
• fadt: style shorthand that represents all Duotone Thin icons in @duotone-thin-svg-icons *
• fass: style shorthand that represents all Sharp Solid icons in @sharp-solid-svg-icons *
• fasds: style shorthand that represents all Sharp Duotone Solid icons in @sharp-duotone-solid-svg-icons *
• faThreads, faFontAwesome, faHatCowboy, and faHatChef: Adding each of these icons individually allows us to use them without importing all the icons in the style

* For the packages above marked with a ”*”, the import adds all the icons in that package/style. Which makes it easy to add any of the icons in that package using the icon name as a string anywhere in the app. But it’s also a lot of icons.

Be Careful What You Import!

Think twice before importing whole styles with SVG Icon Packages - it can be a LOT of icons!

You can then use any of those icons anywhere in your app without needing to re-import into each component. So if you used icons in a couple of components, that might look something like this:

As a string

<template>
  <font-awesome-icon icon="fa-solid fa-dog" />
  <font-awesome-icon icon="fa-duotone fa-solid fa-circle-user" />
  <font-awesome-icon icon="fa-duotone fa-thin fa-fish" />
  <font-awesome-icon icon="fa-sharp fa-solid fa-hippo" />
  <font-awesome-icon icon="fa-sharp-duotone fa-solid fa-dolphin" />

  <font-awesome-icon icon="fa-brands fa-threads" />
  <font-awesome-icon icon="fa-brands fa-font-awesome" />
  <font-awesome-icon icon="fa-duotone fa-light fa-hat-cowboy" />
  <font-awesome-icon icon="fa-sharp fa-thin fa-hat-chef" />
<template>

As an array

<template>
  <font-awesome-icon :icon="['fas', 'dog']" />
  <font-awesome-icon :icon="['fad', 'circle-user']" />
  <font-awesome-icon :icon="['fadt', 'fish']" />
  <font-awesome-icon :icon="['fass', 'hippo']" />
  <font-awesome-icon :icon="['fasds', 'dolphin']" />

  <font-awesome-icon :icon="['fab', 'threads']" />
  <font-awesome-icon :icon="['fab', 'font-awesome']" />
  <font-awesome-icon :icon="['fadl', 'hat-cowboy']" />
  <font-awesome-icon :icon="['fast', 'hat-chef']" />
</template>

You’ll notice we were able use the imported brand icons without explicitly importing them in the component. And we used the dog, hippo, feather, fish, and dolphin icons without explicitly importing them anywhere. But, each bundle now has over 1000 solid icons plus the two brand icons we added, which is more than we’re using - a good reason to avoid importing a whole style.

Troubleshooting

Missing Icons?

If some of your icons aren’t showing up, make sure you have included the icons - in the style you’re trying to use - in your subset for your Kit (if you’re using the Kit package), or imported the style package for the style of icon you’re trying to use (if you’re using the SVG packages by style).

Importing Hyphenated Icon Names

If you’re having trouble importing icons with hyphenated names (like user-circle, thumbs-up, or face-smile), make sure you’re using the correct import format.

When importing from the Font Awesome package, prepend fa and convert the icon name to PascalCase (also known as UpperCamelCase). For example:

Icon Name	Import Name
circle-user	faCircleUser
thumbs-up	faThumbsUp
face-smile	faFaceSmile

Are you using inline or HTML templates?

If you are using inline templates or HTML as templates you need to be careful to avoid self-closing tags. Read more about self-closing tags on Vue.js. If you are writing these types of templates, you’ll need to adjust the syntax to be valid HTML, like this:

As a string

<!-- Add Icons using String format -->
<font-awesome-icon icon="fa-regular fa-envelope"></font-awesome-icon>
<font-awesome-icon icon="fa-regular fa-circle-user"></font-awesome-icon>

As an array

<!-- Add Icons using Array format -->
<font-awesome-icon :icon="['far', 'envelope']"></font-awesome-icon>
<font-awesome-icon :icon="['far', 'circle-user']"></font-awesome-icon>

Want to use computed or component properties?

We’ve got those too. Get the low-down on how to add icons as computed or component properties.