unplugin-icons

unplugin-icons

Access thousands of icons as components on-demand universally.

Features

• 🌏 Universal
  • 🤹 Any icon sets - ~150 popular sets with over 200,000 icons, logos, emojis, etc. Powered by Iconify.
  • 📦 Major build tools - Vite, Webpack, Rollup, Nuxt, Rspack, etc. Powered by unplugin.
  • 🚀 Major frameworks - Vanilla, Web Components, React, Vue 3, Vue Vapor, Solid, Svelte, and more. Contribute.
  • 🍱 Any combinations of them!
• ☁️ On-demand - Only bundle the icons you really use, 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.
• 📥 Custom icons - load your custom icons to get universal integrations at ease.
• 📲 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

From v24.0.0 unplugin-icons requires Node 20 or above: unplugin v3.0.0 requires Node 20 or above.

Quick Start

Basic Usage

Import icons using the convention ~icons/{collection}/{icon} and use them as components. Auto importing is also supported.

React Example:

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 Example:

<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>

Installation

Note: This package is ESM-only. Make sure your project uses ES modules ("type": "module" in package.json or .mjs file extensions).

Step 1: Install the Plugin

npm i -D unplugin-icons

Step 2: Install Icon Data

We use Iconify as the icons data source (supports 100+ icon sets).

Option A: Install Full Collection (Recommended for flexibility)

npm i -D @iconify/json

This installs all icon sets (~120MB). Only icons you actually use will be bundled in production.

Option B: Install Individual Icon Sets

Install only the icon sets you need:

npm i -D @iconify-json/mdi @iconify-json/carbon

Option C: Auto Install (Experimental)

Let unplugin-icons automatically install icon sets when you import them:

Icons({
  autoInstall: true, // Auto-detects npm/yarn/pnpm
})

Examples

Check out the playgrounds page to try examples online in StackBlitz.

Available examples:

• Vite + Vue 3
• Vite + React
• Next.js
• Nuxt 4
• SvelteKit
• Astro
• And more…

Configuration

This section covers how to configure unplugin-icons for different build tools and frameworks.

Build Tools

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

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

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

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

// webpack.config.mjs
import Icons from 'unplugin-icons/webpack'

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

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

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    ['unplugin-icons/nuxt', { /* options */ }]
  ],
})

import IconsResolver from 'unplugin-icons/resolver'
import ViteComponents from 'unplugin-vue-components/vite'

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    'unplugin-icons/nuxt',
  ],
  vite: {
    plugins: [
      ViteComponents({
        resolvers: [
          IconsResolver({/* options */}),
        ],
      }),
    ],
  },
})

import Icons from 'unplugin-icons/rspack'

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

// vue.config.mjs
import Icons from 'unplugin-icons/webpack'

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

import { sveltekit } from '@sveltejs/kit/vite'
import Icons from 'unplugin-icons/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    sveltekit(),
    Icons({
      compiler: 'svelte',
    })
  ]
})

npm i -D @sveltejs/vite-plugin-svelte

import { svelte } from '@sveltejs/vite-plugin-svelte'
import Icons from 'unplugin-icons/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    svelte(),
    Icons({
      compiler: 'svelte',
    }),
  ],
})

// next.config.mjs
import Icons from 'unplugin-icons/webpack'

/** @type {import('next').NextConfig} */
export default {
  reactStrictMode: true,
  webpack(config) {
    config.plugins.push(
      Icons({
        compiler: 'jsx',
        jsx: 'react'
      })
    )

    return config
  }
}

import IconArrowRight from '~icons/dashicons/arrow-right.jsx';
                                                     // ^-- write `.jsx` to avoid
                                                     // https://github.com/antfu/unplugin-icons/issues/103
// ...some code later
<IconArrowRight />

// esbuild.config.js
import { build } from 'esbuild'
import Icons from 'unplugin-icons/esbuild'

build({
  /* ... */
  plugins: [
    Icons({
      /* options */
    }),
  ],
})

// astro.config.mjs
import { defineConfig } from 'astro/config'
import Icons from 'unplugin-icons/vite'

// https://astro.build/config
export default defineConfig({
  vite: {
    plugins: [
      Icons({
        compiler: 'astro',
      }),
    ],
  },
})

import Vue from '@astrojs/vue'
// astro.config.mjs
import { defineConfig } from 'astro/config'
import Icons from 'unplugin-icons/vite'

// https://astro.build/config
export default defineConfig({
  integrations: [
    Vue(),
  ],
  vite: {
    plugins: [
      Icons({
        compiler: 'vue3',
      }),
    ],
  },
})

Frameworks

Configure the compiler option based on your framework. Some frameworks may require additional peer dependencies.

Icons({ compiler: 'vue3' })

npm i -D @vue/compiler-sfc

{
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/vue"
    ]
  }
}

Icons({ compiler: 'vue-vapor' })

npm i -D @vue/compiler-vapor

{
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/vue"
    ]
  }
}

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

npm i -D @svgr/core @svgr/plugin-jsx

{
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/react"
    ]
  }
}

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

npm i -D @svgr/core @svgr/plugin-jsx

{
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/preact"
    ]
  }
}

Icons({ compiler: 'solid' })

{
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/solid"
    ]
  }
}

Icons({ compiler: 'svelte' })

import 'unplugin-icons/types/svelte'

/// <reference types="svelte" />
/// <reference types="vite/client" />
/// <reference types="unplugin-icons/types/svelte" />

/// <reference types="unplugin-icons/types/svelte4" />

/// <reference types="unplugin-icons/types/svelte3" />

Icons({ compiler: 'astro' })

{
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/astro"
    ]
  }
}

Icons({ compiler: 'vue3' })

{
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/vue"
    ]
  }
}

Icons({ compiler: 'qwik' })

npm i -D @svgx/core

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

npm i -D @svgr/core @svgr/plugin-jsx

{
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/qwik"
    ]
  }
}

Icons({ compiler: 'ember' })

import { ember, extensions } from '@embroider/vite'
import { babel } from '@rollup/plugin-babel'
import Icons from 'unplugin-icons/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    ember(),
    Icons({
      compiler: 'ember',
    }),
    babel({
      babelHelpers: 'runtime',
      extensions,
    }),
  ],
})

{
  "compilerOptions": {
    "types": [
      "unplugin-icons/types/ember"
    ]
  }
}

import { compatBuild } from '@embroider/compat'
import Icons from 'unplugin-icons/webpack'

return compatBuild(app, Webpack, {
    packagerOptions: {
      webpackConfig: {
        plugins: [
          Icons({
            compiler: 'ember',
          }),
        ],
      },
    },
    // ...other options

Raw SVG Import

Available from v0.13.2+

Import icons as raw SVG strings by adding ?raw to the import path. Useful for embedding SVG directly in HTML templates.

Example (Vue 3):

<script setup lang='ts'>
import RawMdiAlarmOff from '~icons/mdi/alarm-off?raw&width=4em&height=4em'
import RawMdiAlarmOff2 from '~icons/mdi/alarm-off?raw&width=1em&height=1em'
</script>

<template>
  <!-- raw example -->
  <pre>
    import RawMdiAlarmOff from '~icons/mdi/alarm-off?raw&width=4em&height=4em'
    {{ RawMdiAlarmOff }}
    import RawMdiAlarmOff2 from '~icons/mdi/alarm-off?raw&width=1em&height=1em'
    {{ RawMdiAlarmOff2 }}
  </pre>
  <!-- svg example -->
  <span v-html="RawMdiAlarmOff" />
  <span v-html="RawMdiAlarmOff2" />
</template>

Custom Icons

Load your own custom icons and use them with the same universal API.

import { promises as fs } from 'node:fs'

// loader helpers
import { FileSystemIconLoader } from 'unplugin-icons/loaders'

Icons({
  customCollections: {
    // key as the collection name
    'my-icons': {
      account: '<svg><!-- ... --></svg>',
      // load your custom icon lazily
      settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
      /* ... */
    },
    'my-other-icons': async (iconName) => {
      // your custom loader here. Do whatever you want.
      // for example, fetch from a remote server:
      return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
    },
    // a helper to load icons from the file system
    // files under `./assets/icons` with `.svg` extension will be loaded as it's file name
    // you can also provide a transform callback to change each icon (optional)
    'my-yet-other-icons': FileSystemIconLoader(
      './assets/icons',
      svg => svg.replace(/^<svg /, '<svg fill="currentColor" '),
    ),
  },
})

Then use as

import IconAccount from '~icons/my-icons/account'
import IconFoo from '~icons/my-other-icons/foo'
import IconBar from '~icons/my-yet-other-icons/bar'

💡 SVG Authoring Tips:

• To make your icons color adaptable, set fill="currentColor" or stroke="currentColor" in your SVG.
• Leave the height and width unspecified, we will set them for you.

Auto-Import with Resolver

When using auto-importing, register your custom collection names:

IconResolver({
  customCollections: [
    'my-icons',
    'my-other-icons',
    'my-yet-other-icons',
  ],
})

See the Vue 3 example for a complete setup.

External Collection Packages

Load icons from third-party packages that follow the Iconify format.

Requirements:

External packages must include an icons.json file in IconifyJSON format. See Exporting icon set as JSON package for details.

For example, you can use an-awesome-collection or @my-awesome-collections/some-collection to load your custom or third party icons:

// loader helpers
import { ExternalPackageIconLoader } from 'unplugin-icons/loaders'

Icons({ customCollections: ExternalPackageIconLoader('my-awesome-collection') })

When using with resolvers for auto-importing, remember you will need to tell it your custom collection names:

IconResolver({
  customCollections: [
    'my-awesome-collection',
  ],
})

You can also combine it with FileSystemIconLoader or with other custom icon loaders:

// loader helpers
import { ExternalPackageIconLoader, FileSystemIconLoader } from 'unplugin-icons/loaders'

Icons({
  customCollections: {
    ...ExternalPackageIconLoader('an-awesome-collection'),
    ...ExternalPackageIconLoader('@my-awesome-collections/some-collection'),
    ...ExternalPackageIconLoader('@my-awesome-collections/some-other-collection'),
    'my-yet-other-icons': FileSystemIconLoader(
      './assets/icons',
      svg => svg.replace(/^<svg /, '<svg fill="currentColor" '),
    ),
  },
})

See the Vue 3 example for a complete setup.

File System Icon Loader with Hot Module Replacement (HMR)

Load icons from your local file system including HMR when you change your local SVG files.

Since unplugin-icons is built on top of unplugin, HMR should work out of the box with Vite, Webpack, and Rspack. You can also use it with other build tools that support HMR when running the dev server.

⚠️ Important HMR Limitations:

• Directory Location: Your local SVG folder must reside inside your project’s root directory. If the folder is placed outside the root, the underlying bundler’s file watcher may not detect file changes, causing HMR to fail.
• Ember + Webpack: Legacy watcher architectures (like Ember CLI with Broccoli) are extremely strict with their sandboxed environments. Your custom SVG folder must be placed inside a natively watched tree (such as app/). If placed elsewhere, the file system events will be ignored by Broccoli and will never notify Webpack to invalidate the virtual module cache.

For example:

// loader helpers
import { FileSystemHMRIconLoader } from 'unplugin-icons/loaders'

Icons({ customCollections: FileSystemHMRIconLoader('./assets/my-local-svg-folder', 'my-awesome-collection') })

When using with resolvers for auto-importing, remember you will need to tell it your custom collection names:

IconResolver({
  customCollections: [
    'my-awesome-collection',
  ],
})

You can also combine it with FileSystemIconLoader or with other custom icon loaders:

// loader helpers
import { ExternalPackageIconLoader, FileSystemHMRIconLoader, FileSystemIconLoader } from 'unplugin-icons/loaders'

Icons({
  customCollections: {
    ...ExternalPackageIconLoader('an-awesome-collection'),
    ...ExternalPackageIconLoader('@my-awesome-collections/some-collection'),
    ...FileSystemHMRIconLoader('./assets/my-local-svg-folder', 'my-awesome-collection'),
    'my-yet-other-icons': FileSystemIconLoader(
      './assets/icons',
      svg => svg.replace(/^<svg /, '<svg fill="currentColor" '),
    ),
  },
})

See the Vue 3 example for a complete setup.

Icon Customization

Customize individual icons or entire collections using iconCustomizer in your config or query parameters when importing.

Precedence: Query params > iconCustomizer > default configuration

Works with all icon sources: custom loaders, inlined collections, and Iconify collections.

For example, you can configure iconCustomizer to change all icons for a collection or individual icons on a collection:

import { promises as fs } from 'node:fs'

// loader helpers
import { FileSystemIconLoader } from 'unplugin-icons/loaders'

Icons({
  customCollections: {
    // key as the collection name
    'my-icons': {
      account: '<svg><!-- ... --></svg>',
      // load your custom icon lazily
      settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
      /* ... */
    },
    'my-other-icons': async (iconName) => {
      // your custom loader here. Do whatever you want.
      // for example, fetch from a remote server:
      return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
    },
    // a helper to load icons from the file system
    // files under `./assets/icons` with `.svg` extension will be loaded as it's file name
    // you can also provide a transform callback to change each icon (optional)
    'my-yet-other-icons': FileSystemIconLoader(
      './assets/icons',
      svg => svg.replace(/^<svg /, '<svg fill="currentColor" '),
    ),
  },
  iconCustomizer(collection, icon, props) {
    // customize all icons in this collection
    if (collection === 'my-other-icons') {
      props.width = '4em'
      props.height = '4em'
    }
    // customize this icon in this collection
    if (collection === 'my-icons' && icon === 'account') {
      props.width = '6em'
      props.height = '6em'
    }
    // customize this @iconify icon in this collection
    if (collection === 'mdi' && icon === 'account') {
      props.width = '2em'
      props.height = '2em'
    }
  },
})

or you can use query params to apply to individual icons:

<script setup lang='ts'>
import MdiAlarmOff from 'virtual:icons/mdi/alarm-off?width=4em&height=4em'
import MdiAlarmOff2 from 'virtual:icons/mdi/alarm-off?width=1em&height=1em'
</script>

<template>
  <!-- width=4em and height=4em -->
  <mdi-alarm-off />
  <!-- width=4em and height=4em -->
  <MdiAlarmOff />
  <!-- width=1em and height=1em -->
  <MdiAlarmOff2 />
</template>

See the Vue 3 example for a complete implementation.

Global Icon Transformation

Apply transformations to all custom icons during loading. Useful for adding default attributes like fill="currentColor".

Icons({
  customCollections: {
    // key as the collection name
    'my-icons': {
      account: '<svg><!-- ... --></svg>',
      /* ... */
    },
  },
  transform(svg, collection, icon) {
    // apply fill to this icon on this collection
    if (collection === 'my-icons' && icon === 'account')
      return svg.replace(/^<svg /, '<svg fill="currentColor" ')

    return svg
  },
})

Advanced Custom Icon Set Cleanup

When using this plugin with your custom icons, consider using a cleanup process similar to that done by Iconify for any icons sets. All the tools you need are available in Iconify Tools.

You can check this repo, using unplugin-icons on a SvelteKit project: https://github.com/iconify/tools/tree/main/%40iconify-demo/unplugin-svelte.

Read Cleaning up icons article from Iconify for more details.

Migration from vite-plugin-icons

If you’re upgrading from vite-plugin-icons, follow these steps:

1. Update package.json:

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

2. Update your config file:

import Components from 'unplugin-vue-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(),
  ],
}

3. Update import paths:

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

Note: The virtual:icons prefix still works in Vite, but ~icons is recommended for consistency across all build tools.

Options

Configure default styling and behavior for all icons:

Icons({
  // Icon sizing
  scale: 1.2, // Scale factor relative to 1em (default: 1.2)

  // Default styling
  defaultStyle: '', // CSS styles applied to all icons
  defaultClass: '', // CSS classes applied to all icons

  // Compiler configuration
  compiler: null, // Framework compiler: 'vue3', 'vue-vapor', 'jsx', 'svelte', 'solid', etc.
  jsx: 'react', // JSX framework: 'react' or 'preact' (when compiler: 'jsx')

  // Custom collections
  customCollections: {}, // See [Custom Icons](#custom-icons)

  // Advanced
  iconCustomizer: () => {}, // See [Icon Customization](#icon-customization)
  transform: undefined, // See [Global Icon Transformation](#global-icon-transformation)
  autoInstall: false, // Auto-install icon sets on import
})

Auto Importing

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

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

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

// vite.config.ts
import AutoImport from 'unplugin-auto-import/vite'
import IconsResolver from 'unplugin-icons/resolver'
import Icons from 'unplugin-icons/vite'

export default {
  plugins: [
    AutoImport({
      resolvers: [
        IconsResolver({
          prefix: 'Icon',
          extension: 'jsx',
        }),
      ],
    }),
    Icons({
      compiler: 'jsx', // or 'solid'
    }),
  ],
}

export function Component() {
  return (
    <div>
      <IconCarbonApps />
      <IconMdiAccountBox style="font-size: 2em; color: red" />
    </div>
  )
}

Component Naming

Icons are auto-imported following this naming pattern:

{prefix}-{collection}-{icon}

• prefix: Component name prefix (default: i)
• collection: Iconify collection ID (e.g., mdi, carbon, fa-solid)
• icon: Icon name (kebab-case)

Custom Prefix:

IconsResolver({
  prefix: 'icon', // Use 'icon' instead of 'i'
})

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

No Prefix:

IconsResolver({
  prefix: false,
  enabledCollections: ['mdi'], // Optional: limit to specific collections
})

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

Collection Aliases

Create shorter aliases for long collection names:

IconsResolver({
  alias: {
    park: 'icon-park', // Use <icon-park-* /> instead of <icon-icon-park-* />
    fas: 'fa-solid', // Use <icon-fas-* /> instead of <icon-fa-solid-* />
  }
})

Both the alias and full collection name work:

<template>
  <icon-park-abnormal />      <!-- Using alias -->
  <icon-icon-park-abnormal /> <!-- Using full name -->
</template>

Sponsors

This project is part of my Sponsor Program

License

MIT License © 2020-PRESENT Anthony Fu