unplugin-vue-fontawesome

Automatic icon registration for Font Awesome icons in Vue 3 components.

Install

npm i -D unplugin-vue-fontawesome

Vite

// vite.config.ts
import FontAwesome from 'unplugin-vue-fontawesome/vite'

export default defineConfig({
  plugins: [
    FontAwesome({
      collections: 'pro',
      /* options */
    }),
  ],
})

Example: playground/

Rollup

// rollup.config.js
import FontAwesome from 'unplugin-vue-fontawesome/rollup'

export default {
  plugins: [
    FontAwesome({
      collections: 'pro',
      /* options */
    }),
  ],
}

Webpack

// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('unplugin-vue-fontawesome/webpack')({
      collections: 'pro',
      /* options */
    }),
  ],
}

Nuxt

// nuxt.config.js
export default {
  buildModules: [
    [
      'unplugin-vue-fontawesome/nuxt',
      {
        collections: 'pro',
        /* options */
      },
    ],
  ],
}

This module works for both Nuxt 2 and Nuxt Vite

Vue CLI

// vue.config.js
module.exports = {
  configureWebpack: {
    plugins: [
      require('unplugin-vue-fontawesome/webpack')({
        collections: 'pro',
        /* options */
      }),
    ],
  },
}

esbuild

// esbuild.config.js
import { build } from 'esbuild'
import FontAwesome from 'unplugin-vue-fontawesome/esbuild'

build({
  plugins: [FontAwesome({
    collections: 'pro',
    /* options */
  })],
})

Usage

The plugin is intended to be used together with @fortawesome/vue-fontawesome

The following kinds of icon usage are supported

<!-- regular icon name -->
<FontAwesomeIcon icon="coffee" />

<!-- icon with collection as array -->
<FontAwesomeIcon :icon="['fab', 'vuejs']" />

<!-- icon with collection as string -->
<FontAwesomeIcon icon="fa-regular fa-user" />
<FontAwesomeIcon icon="fa-sharp fa-solid fa-star" />

Limitations

Dynamic icons are not supported, so those have to be registered manually.

import { faIconName } from '@fortawesome/free-solid-svg-icons'
import { library } from '@fortawesome/fontawesome-svg-core'
library.add(faIconName)

Note: It is not recommended to do this inside <script setup> since that will register the icons every time the component mounts.

Configuration

The following show the default values of the configuration

FontAwesome({
  // the fontawesome collections to use
  collections: 'free',

  // collection that is used if no collection is specified
  defaultCollection: 'solid',

  // prop names to be tested for icons
  props: ['icon'],

  // component names to be tested for icons, use an empty array to check all components
  components: ['icon', 'font-awesome-icon'],

  // filters for transforming targets
  include: [/\.vue$/, /\.vue\?vue/],
  exclude: [/node_modules/, /\.git/],
})

Collections

The following presets are available for the collections option: