unplugin-icons
Access thousands of icons as components on-demand universally.
Features
- 🌏 Universal
- 🤹 Any icon sets - 100+ popular sets with over 10,000 icons, logos, emojis, etc. Powered by Iconify.
- 📦 Major build tools - Vite, Webpack, Rollup, Nuxt, etc. Powered by unplugin.
- 🪜 Major frameworks - Vanilla, Web Components, React, Vue 3, Vue 2, Solid, Svelte, and more. Contribute.
- 🍱 Any combinations of them!
- ☁️ On-demand - Only bundle the icons you really uses, while having all the options.
- 🖨 SSR / SSG friendly - Ship the icons with your page, no more FOUC.
- 🌈 Stylable - Change size, color, or even add animations as you would with styles and classes.
- 📲 Auto Importing - Use icons as components directly in your template.
- 🦾 TypeScript support.
- 🔍 Browse Icons
vite-plugin-icons
has been renamed to unplugin-icons
, see the migration guide.
Usage
Import icons names with the convension ~icons/{collection}/{icon}
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
import Icons from 'unplugin-icons/vite'
export default defineConfig({
plugins: [
Icons({ }),
],
})
Rollup
import Icons from 'unplugin-icons/rollup'
export default {
plugins: [
Icons({ }),
],
}
Webpack
module.exports = {
plugins: [
require('unplugin-icons/webpack')({ })
]
}
Nuxt
export default {
buildModules: [
['unplugin-icons/nuxt', { }],
],
}
This module works for both Nuxt 2 and Nuxt Vite
Vue CLI
module.exports = {
configureWebpack: {
plugins: [
require('unplugin-icons/webpack')({ }),
],
},
}
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",
]
}
}
Solid
Icons({ compiler: 'solid' })
Type Declarations
// tsconfig.json
{
"compilerOptions": {
"types": [
"unplugin-icons/types/solid",
]
}
}
Migrate from vite-plugin-icons
package.json
{
"devDependencies": {
- "vite-plugin-icons": "*",
+ "unplugin-icons": "^0.7.0",
}
}
vite.config.json
import Components from 'unplugin-components/vite'
- import Icons, { ViteIconsResolver } from 'vite-plugin-icons'
+ import Icons from 'unplugin-icons/vite'
+ import IconsResolver from 'unplugin-icons/resolver'
export default {
plugins: [
Vue(),
Components({
resolvers: IconsResolver(),
}),
Icons(),
],
}
*
- imports usage
- import IconComponent from 'virtual:vite-icons/collection/name'
+ import IconComponent from '~icons/collection/name'
You can still use virtual:icons
prefix in Vite if you prefer, but it's not yet supported in Webpack, we are unifying it as a workaround in the docs.
Options
You can set default styling for all icons.
The following config shows the default values of each option:
Icons({
scale: 1.2,
defaultStyle: '',
defaultClass: '',
compiler: null,
jsx: 'react'
})
Auto Importing
Vue 2 & 3
Use with unplugin-vue-components
For example in Vite:
import Vue from '@vitejs/plugin-vue'
import Icons from 'unplugin-icons/vite'
import IconsResolver from 'unplugin-icons/resolver'
import Components from 'unplugin-vue-components/vite'
export default {
plugins: [
Vue(),
Components({
resolvers: 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>
React & Solid
Use with unplugin-auto-import
For example in Vite:
import Icons from 'unplugin-icons/vite'
import IconsResolver from 'unplugin-icons/resolver'
import AutoImport from 'unplugin-auto-import/vite'
export default {
plugins: [
AutoImport({
resolvers: [
IconsResolver({
prefix: 'Icon',
extension: 'jsx'
})
],
}),
Icons({
compiler: 'jsx'
}),
],
}
Then you can use any icons with the prefix Icon
as you want without explicit importing. Type declarations will be generated on the fly.
export function Component() {
return (
<div>
<IconCarbonApps />
<IconMdiAccountBox style="font-size: 2em; color: red"/>
</div>
)
}
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
IconsResolver({
prefix: 'icon'
})
<template>
<icon-mdi-account />
</template>
Non-prefix mode is also supported
IconsResolver({
prefix: false,
enabledCollections: ['mdi']
})
<template>
<mdi-account />
</template>
This project is part of my Sponsor Program
License
MIT License © 2020-PRESENT Anthony Fu