{"id":12615,"library":"vue-unicons","title":"Vue Unicons","description":"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.","status":"active","version":"3.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/antonreshetov/vue-unicons","tags":["javascript","vue","vuejs","vue-component","vue-icons","components","icons","typescript"],"install":[{"cmd":"npm install vue-unicons","lang":"bash","label":"npm"},{"cmd":"yarn add vue-unicons","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-unicons","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a Vue component library and requires Vue as a peer dependency for runtime.","package":"vue","optional":false}],"imports":[{"note":"For Vue 3 applications, import Unicon directly. For Vue 2, use the specific UMD build from 'dist'.","wrong":"import Unicon from 'vue-unicons/dist/vue-unicons-vue2.umd'","symbol":"Unicon","correct":"import Unicon from 'vue-unicons'"},{"note":"Specifically for Vue 2 projects, you must import the UMD build for Vue 2 compatibility.","wrong":"import Unicon from 'vue-unicons'","symbol":"Unicon (Vue 2)","correct":"import Unicon from 'vue-unicons/dist/vue-unicons-vue2.umd'"},{"note":"Individual icons are named with a `uni` prefix and imported from the `dist/icons` path. Do not drop the prefix in import statements.","wrong":"import { CarWash } from 'vue-unicons/dist/icons'","symbol":"uniCarWash","correct":"import { uniCarWash } from 'vue-unicons/dist/icons'"},{"note":"When adding icons to the Unicon library, you must pass the imported icon object (e.g., `uniCarWash`), not just the string name.","wrong":"Unicon.add(['icon-name']);","symbol":"Unicon.add","correct":"import { uniIconName } from 'vue-unicons/dist/icons'; Unicon.add([uniIconName]);"}],"quickstart":{"code":"import { createApp } from 'vue'\nimport App from './App.vue'\nimport Unicon from 'vue-unicons'\nimport { uniLayerGroupMonochrome, uniCarWash } from 'vue-unicons/dist/icons'\n\n// Add the desired icons to the Unicon library\nUnicon.add([uniLayerGroupMonochrome, uniCarWash])\n\n// Install Unicon as a Vue plugin, optionally with global configuration\ncreateApp(App)\n  .use(Unicon, {\n    fill: 'deeppink',\n    height: 32,\n    width: 32\n  })\n  .mount('#app')\n\n// In App.vue template:\n// <template>\n//   <div>\n//     <unicon name=\"car-wash\" fill=\"limegreen\"></unicon>\n//     <unicon name=\"layer-group\" fill=\"royalblue\" icon-style=\"monochrome\"></unicon>\n//   </div>\n// </template>","lang":"typescript","description":"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."},"warnings":[{"fix":"Review the Unicons changelog (linked from vue-unicons GitHub) for specific icon changes and update icon names/usage in your application accordingly.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"If migrating from v1.x, ensure icon names and styles are compatible. Adopt the `icon-style='monochrome'` prop for monochrome versions.","message":"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.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"For Vue 3: `import Unicon from 'vue-unicons'`. For Vue 2: `import Unicon from 'vue-unicons/dist/vue-unicons-vue2.umd'`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always convert the `uni` prefixed camelCase import name to kebab-case for the `name` prop (e.g., `uniLayerGroupMonochrome` -> `layer-group`).","message":"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\">`).","severity":"gotcha","affected_versions":">=1.0.0"},{"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=\"...\"/>' }`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The Unicon plugin was not correctly installed with Vue, or the component is being used before the plugin is registered.","error":"Failed to resolve component: unicon"},{"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.","cause":"The `Unicon` object was not correctly imported, or the wrong import path was used for your Vue version.","error":"Cannot read properties of undefined (reading 'add') OR Unicon.add is not a function"},{"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`).","cause":"The requested icon was not added to the Unicon library using `Unicon.add()`, or the icon name in the template is incorrect.","error":"Error: [vue-unicons]: The icon \"your-icon-name\" does not exist."}],"ecosystem":"npm"}