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

Usage

Import icons names with the convention ~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>
      
      
    </div>
  )
}

Vue

<template>
  
  
</template>

Install

Plugin

npm i -D unplugin-icons

Icons Data

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

You have two ways to install them:

Install Full Collection

npm i -D @iconify/json

@iconify/json (~120MB) includes all the iconsets from Iconify so you can install once and use any of them as you want (only the icons you actually use will be bundle into the production build).

Install by Icon Set

If you only want to use a few of the icon sets and don't want to download the entire collection, you can also install them individually with @iconify-json/[collection-id]. For example, to install Material Design Icons, you can do:

npm i -D @iconify-json/mdi

To boost your workflow, it's also possible to let unplugin-icons handle that installation by enabling the autoInstall option.

Icons({
  // experimental
  autoInstall: true,
})

It will install the icon set when you import them. The right package manager will be auto-detected (npm, yarn or pnpm).

Examples

You can play online with the examples in this repo in StackBlitz, see playgrounds page.

Fork any of the online examples and reproduce the issue you're facing, then share the link with us.

Configuration

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.js
module.exports = {
  /* ... */
  plugins: [
    require('unplugin-icons/webpack').default({ /* options */ }),
  ],
}

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

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

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

// 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.js
module.exports = {
  configureWebpack: {
    plugins: [
      require('unplugin-icons/webpack').default({ /* options */ }),
    ],
  },
}

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

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

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

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

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

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

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

// next.config.js
/** @type {import('next').NextConfig} */
module.exports = {
  reactStrictMode: true,
  webpack(config) {
    config.plugins.push(
      require('unplugin-icons/webpack').default({
        compiler: 'jsx',
        jsx: 'react'
      })
    )

    return config
  },
}

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

// 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',
      }),
    ],
  },
})

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

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

Frameworks

npm i -D @vue/compiler-sfc

Icons({ compiler: 'vue3' })

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

npm i -D vue-template-compiler

Icons({ compiler: 'vue2' })

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

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

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

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

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

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

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

Icons({ compiler: 'solid' })

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

Icons({ compiler: 'svelte' })

import 'unplugin-icons/types/svelte'

/// 
/// 
/// 

/// 
/// 
/// 

/// 
/// 
/// 

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

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

npm i -D @svgx/core

Icons({ compiler: 'qwik' })

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

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

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

Use RAW compiler from query params

From v0.13.2 you can also use raw compiler to access the svg icon and use it on your html templates, just add raw to the icon query param.

For example, using vue3:

<template>
  
  <pre>    import RawMdiAlarmOff from '~icons/mdi/alarm-off?raw&amp;width=4em&amp;height=4em'
    {{ RawMdiAlarmOff }}
    import RawMdiAlarmOff2 from '~icons/mdi/alarm-off?raw&amp;width=1em&amp;height=1em'
    {{ RawMdiAlarmOff2 }}
  </pre>
  
  <span>
  <span>
</span></span></template>

Custom Icons

From v0.11, you can now load your own icons!

From v0.13 you can also provide a transform callback to FileSystemIconLoader.

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: () =&gt; fs.readFile('./path/to/my-icon.svg', 'utf-8'),
      /* ... */
    },
    'my-other-icons': async (iconName) =&gt; {
      // 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 =&gt; 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 =&gt; svg.replace(/^<svg fill="currentColor"> 💡 SVG Authoring Tips:
&gt; - To make your icons color adaptable, set `fill="currentColor"` or `stroke="currentColor"` in your SVG.
&gt; - Leave the `height` and `width` unspecified, we will set them for you.

### Use with Resolver

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

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

See the Vue 3 + Vite example.

Use Custom External Collection Packages

From version v0.18.3 you can use other packages to load icons from others authors.

WARNING: external packages must include icons.json file with the icons data in IconifyJSON format, which can be exported with Iconify Tools. Check Exporting icon set as JSON package for more 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 =&gt; svg.replace(/^<svg name="" for="" fill="currentColor"></svg>',
      // load your custom icon lazily
      settings: () =&gt; fs.readFile('./path/to/my-icon.svg', 'utf-8'),
      /* ... */
    },
    'my-other-icons': async (iconName) =&gt; {
      // 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 =&gt; 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 =&gt; svg.replace(/^<svg in="" fill="currentColor">

```vue

See src/App.vue component and vite.config.ts configuration on vite-vue3 example project.

Global Custom Icon Transformation

From version 0.14.2, when loading your custom icons, you can transform them, for example adding fill attribute with 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' &amp;&amp; icon === 'account')
      return svg.replace(/^<svg default="" in="" for="" by="" fill="currentColor"> 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:

```ts
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 unplugin-vue-components

For example in Vite:

// vite.config.js
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>
  
  
</template>

// vite.config.js
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', // or 'solid'
    }),
  ],
}

export function Component() {
  return (
    <div>
      
      
    </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>
  
</template>

Non-prefix mode is also supported

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

<template>
  
</template>

Collection Aliases

When using component resolver, you have to use the name of the collection that can be long or redundant: for example, when using icon-park collection you need to use it like this ``.

You can add an alias for any collection to the IconResolver plugin:

IconsResolver({
  alias: {
    park: 'icon-park',
    fas: 'fa-solid',
    // ...
  }
})

You can use the alias or the collection name, the plugin will resolve both.

Following with the example and configuring the plugin with previous alias entry, you can now use or.

Sponsors

This project is part of my Sponsor Program

License

MIT License © 2020-PRESENT Anthony Fu