Vue Unicons

3.3.1 · active · verified Sun Apr 19

vue-unicons is a library that provides access to over 1000 pixel-perfect SVG icons from the Iconscout Unicons collection, integrated directly as Vue components. The current stable version is 3.3.1. Releases occur periodically, often tied to updates in the upstream Unicons library, alongside bug fixes and minor feature enhancements. Key differentiators include its simple integration into Vue 2 and Vue 3 projects, offering both line and monochrome icon styles, and allowing for global configuration of icon properties like `fill`, `height`, and `width`. It simplifies icon management by making each icon a reusable Vue component, contrasting with traditional icon font or raw SVG sprite approaches.

Common errors

```
Failed to resolve component: unicon
```
cause The Unicon plugin was not correctly installed with Vue, or the component is being used before the plugin is registered.

fix Ensure `createApp(App).use(Unicon).mount('#app')` (Vue 3) or `Vue.use(Unicon)` (Vue 2) is called before your root Vue instance is mounted.
```
Cannot read properties of undefined (reading 'add') OR Unicon.add is not a function
```
cause The `Unicon` object was not correctly imported, or the wrong import path was used for your Vue version.

fix Verify the `import Unicon from '...'` statement is correct for your Vue version: `import Unicon from 'vue-unicons'` for Vue 3, and `import Unicon from 'vue-unicons/dist/vue-unicons-vue2.umd'` for Vue 2.
```
Error: [vue-unicons]: The icon "your-icon-name" does not exist.
```
cause The requested icon was not added to the Unicon library using `Unicon.add()`, or the icon name in the template is incorrect.

fix First, import the specific icon (e.g., `import { uniYourIconName } from 'vue-unicons/dist/icons'`). Then, ensure `Unicon.add([uniYourIconName])` is called before your app mounts. Finally, verify the `name` prop in your `<unicon>` component uses the correct kebab-case name (e.g., `uniYourIconName` -> `your-icon-name`).

Warnings

breaking Version 3.0.0 updated the underlying Unicons library to 3.0.6, potentially introducing changes to icon availability, names, or SVG paths. Always verify icon rendering and usage after a major version upgrade.
Fix: Review the Unicons changelog (linked from vue-unicons GitHub) for specific icon changes and update icon names/usage in your application accordingly.
breaking Version 2.0.0 introduced 'Monochrome icons style' and additional icons. While not explicitly breaking for existing usage, it changed the internal structure and introduced new features that might require adjustments if you were using undocumented internal APIs.
Fix: If migrating from v1.x, ensure icon names and styles are compatible. Adopt the `icon-style='monochrome'` prop for monochrome versions.
gotcha The import path for the main Unicon plugin differs between Vue 2 and Vue 3 projects. Using the incorrect path will lead to runtime errors or module resolution failures.
Fix: For Vue 3: `import Unicon from 'vue-unicons'`. For Vue 2: `import Unicon from 'vue-unicons/dist/vue-unicons-vue2.umd'`.
gotcha When using an icon in your template, you must use its kebab-case name *without* the `uni` prefix, even though the imported symbol has the prefix (e.g., `uniCarWash` becomes `<unicon name="car-wash">`).
Fix: Always convert the `uni` prefixed camelCase import name to kebab-case for the `name` prop (e.g., `uniLayerGroupMonochrome` -> `layer-group`).
gotcha When adding custom SVG icons, ensure the `path` property contains only the inner SVG path data, not the full `<svg>` tag. Also, ensure the custom icon object includes `name`, `style`, and `path` properties.
Fix: Copy only the `d="..."` content from within the `<path>` tag of your custom SVG. Ensure the custom icon object structure matches `{ name: 'my-custom-icon', style: 'line', path: '<path d="..."/>' }`.

Install

npm install vue-unicons npm
yarn add vue-unicons yarn
pnpm add vue-unicons pnpm

Imports

Unicon
wrong:
```
import Unicon from 'vue-unicons/dist/vue-unicons-vue2.umd'
```
correct:
```
import Unicon from 'vue-unicons'
```
For Vue 3 applications, import Unicon directly. For Vue 2, use the specific UMD build from 'dist'.
Unicon (Vue 2)
wrong:
```
import Unicon from 'vue-unicons'
```
correct:
```
import Unicon from 'vue-unicons/dist/vue-unicons-vue2.umd'
```
Specifically for Vue 2 projects, you must import the UMD build for Vue 2 compatibility.
uniCarWash
wrong:
```
import { CarWash } from 'vue-unicons/dist/icons'
```
correct:
```
import { uniCarWash } from 'vue-unicons/dist/icons'
```
Individual icons are named with a `uni` prefix and imported from the `dist/icons` path. Do not drop the prefix in import statements.
Unicon.add
wrong:
```
Unicon.add(['icon-name']);
```
correct:
```
import { uniIconName } from 'vue-unicons/dist/icons'; Unicon.add([uniIconName]);
```
When adding icons to the Unicon library, you must pass the imported icon object (e.g., `uniCarWash`), not just the string name.

Quickstart

This quickstart demonstrates how to globally register specific Unicons for a Vue 3 application, set default properties, and then use them in a template. It covers importing the plugin and individual icons, and applying global configuration.

import { createApp } from 'vue'
import App from './App.vue'
import Unicon from 'vue-unicons'
import { uniLayerGroupMonochrome, uniCarWash } from 'vue-unicons/dist/icons'

// Add the desired icons to the Unicon library
Unicon.add([uniLayerGroupMonochrome, uniCarWash])

// Install Unicon as a Vue plugin, optionally with global configuration
createApp(App)
  .use(Unicon, {
    fill: 'deeppink',
    height: 32,
    width: 32
  })
  .mount('#app')

// In App.vue template:
// <template>
//   <div>
//     <unicon name="car-wash" fill="limegreen"></unicon>
//     <unicon name="layer-group" fill="royalblue" icon-style="monochrome"></unicon>
//   </div>
// </template>

view raw JSON →