unplugin-icons

What is unplugin-icons?

unplugin-icons is an npm package that provides a convenient way to use icons from various icon sets in your projects. It supports multiple frameworks like Vue, React, and Svelte, and allows you to import icons on-demand, reducing the bundle size.

What are unplugin-icons's main functionalities?

On-Demand Icon Import

This feature allows you to import only the icons you need, which helps in reducing the bundle size. The code sample demonstrates how to import and use a specific icon from the 'bi' (Boxicons) set in a React component.

import { Icon } from 'unplugin-icons';
import { BiAlarm } from 'unplugin-icons/bi';

const MyComponent = () => (
  <div>
    <Icon icon={BiAlarm} />
  </div>
);

Framework Support

unplugin-icons supports multiple frameworks like Vue, React, and Svelte. The code sample shows how to use an icon in a Vue component.

import { defineComponent } from 'vue';
import { BiAlarm } from 'unplugin-icons/bi';

export default defineComponent({
  components: { BiAlarm },
  template: '<BiAlarm />'
});

Custom Icon Sets

You can also use custom icon sets with unplugin-icons. The code sample demonstrates how to import and use a custom icon in a React component.

import { Icon } from 'unplugin-icons';
import { MyCustomIcon } from './my-custom-icons';

const MyComponent = () => (
  <div>
    <Icon icon={MyCustomIcon} />
  </div>
);

Other packages similar to unplugin-icons

react-icons

react-icons is a popular package for including icons in React applications. It supports a wide range of icon libraries and allows for easy integration. Compared to unplugin-icons, react-icons is more focused on React and does not offer the same level of support for other frameworks.

vue-awesome

vue-awesome is a package for using Font Awesome icons in Vue applications. It provides a simple way to include and customize Font Awesome icons. Unlike unplugin-icons, vue-awesome is limited to Font Awesome and does not support other icon sets.

svelte-icons

svelte-icons is a package for using icons in Svelte applications. It supports multiple icon sets and provides a simple API for including icons. While it offers similar functionality to unplugin-icons, it is specifically designed for Svelte.

README

unplugin-icons

Access thousands of icons as components on-demand universally.

• Any icon sets - 90+ popular iconsets, powered by Iconify
• Major build tools - Vite, Webpack, Rollup, Nuxt, etc. powered by unplugin
• Major frameworks - React, Vue 3, Vue 2, and contribute more
• Any combinations of them!
• Browser the icons

vite-plugin-icons has been renamed to unplugin-icons, see the migration guide.

Usage

Import icons names with the prefix ~icons/ and use them directly as components. Auto importing is also possible.

React

import IconAccessibility from '~icons/carbon/accessibility'
import IconAccountBox from '~icons/mdi/account-box'

function App() {
  return (
    <div>
      <IconAccessibility />
      <IconAccountBox style={{ fontSize: '2em', color: 'red' }}/>
    </div>
  )
}

Vue

<script setup>
import IconAccessibility from '~icons/carbon/accessibility'
import IconAccountBox from '~icons/mdi/account-box'
</script>

<template>
  <icon-accessibility/>
  <icon-account-box style="font-size: 2em; color: red"/>
</template>

Install

Install the plugin and peer dependency @iconify/json

npm i -D unplugin-icons @iconify/json

Build Tools

Vite

// vite.config.ts
import Icons from 'unplugin-icons/vite'

export default defineConfig({
  plugins: [
    Icons({ /* options */ }),
  ],
})

Rollup

// rollup.config.js
import Icons from 'unplugin-icons/rollup'

export default {
  plugins: [
    Icons({ /* options */ }),
  ],
}

Webpack

// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('unplugin-icons/webpack')({ /* options */ })
  ]
}

Nuxt

// nuxt.config.js
export default {
  buildModules: [
    ['unplugin-icons/nuxt', { /* options */ }],
  ],
}

This module works for both Nuxt 2 and Nuxt Vite

Vue CLI

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

Frameworks

Vue 3

Vue 3 support requires peer dependency @vue/compiler-sfc:

npm i -D @vue/compiler-sfc

Icons({ compiler: 'vue3' })

Type Declarations

// tsconfig.json
{ 
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/vue",
    ]
  }
}

Vue 2

Vue 2 support requires peer dependency vue-template-compiler:

npm i -D vue-template-compiler

Icons({ compiler: 'vue2' })

Type Declarations

// tsconfig.json
{ 
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/vue",
    ]
  }
}

React

JSX support requires peer dependency @svgr/core:

npm i -D @svgr/core

Icons({ compiler: 'jsx', jsx: 'react' })

Type Declarations

// tsconfig.json
{ 
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/react",
    ]
  }
}

Preact

JSX support requires peer dependency @svgr/core:

npm i -D @svgr/core

Icons({ compiler: 'jsx', jsx: 'preact' })

Type Declarations

// tsconfig.json
{ 
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/preact",
    ]
  }
}

Migrate from vite-plugin-icons

package.json

{
  "devDependencies": {
-   "vite-plugin-icons": "*",
+   "unplugin-icons": "^0.7.0",
  }
}

vite.config.json

import Components from 'vite-plugin-components'
- import Icons, { ViteIconsResolver } from 'vite-plugin-icons'
+ import Icons from 'unplugin-icons/vite'
+ import IconsResolver from 'unplugin-icons/resolver'

export default {
  plugins: [
    Vue(),
    Components({
      customComponentResolvers: IconsResolver(),
    }),
    Icons(),
  ],
}

* - imports usage

- import IconComponent from 'virtual:vite-icons/collection/name'
+ import IconComponent from '~icons/collection/name'

Options

You can set default styling for all icons. The following config shows the default values of each option:

Icons({
  scale: 1.2, // Scale of icons against 1em
  defaultStyle: '', // Style apply to icons
  defaultClass: '', // Class names apply to icons
  compiler: null, // 'vue2', 'vue3', 'jsx'
  jsx: 'react' // 'react' or 'preact'
})

Auto Importing

Use with vite-plugin-components (>= v0.5.5)

// vite.config.js
import Vue from '@vitejs/plugin-vue'
import Components from 'vite-plugin-components'
import Icons from 'unplugin-icons/vite'
import IconsResolver from 'unplugin-icons/resolver'

export default {
  plugins: [
    Vue(),
    Components({
      customComponentResolvers: IconsResolver(),
    }),
    Icons(),
  ],
}

Then you can use any icons as you want without explicit importing (only the used icons will be bundled)

<template>
  <i-carbon-accessibility/>
  <i-mdi-account-box style="font-size: 2em; color: red"/>
</template>

Name Conversion

When using component resolver, you have to follow the name conversion for icons to be properly inferred.

{prefix}-{collection}-{icon}

The collection field follows Iconify's collection IDs.

By default, the prefix is set to i while you can customize via config

export default {
  plugins: [
    Vue(),
    Components({
      customComponentResolvers: IconsResolver({
        componentPrefix: 'icon' // <--
      }),
    }),
    Icons(),
  ],
}

<template>
  <icon-mdi-account />
</template>

Non-prefix mode is also supported

IconsResolver({
  componentPrefix: '', // <--
  // this is optional, default enabling all the collections supported by Iconify
  enabledCollections: ['mdi']
})

<template>
  <mdi-account />
</template>

Sponsors

This project is part of my Sponsor Program

License

MIT License © 2020-PRESENT Anthony Fu