{"id":12591,"library":"vue-svgicon","title":"Vue SVG Icon Component Tool","description":"vue-svgicon is a build-time utility for Vue 2.x projects that converts raw SVG files into optimized Vue components. It provides both a command-line interface (`vsvg`) and a programmatic API to automate the generation process, supporting features like custom icon templates, ES6 module output, and integration with SVGO for further optimization of SVG assets. The current stable version for Vue 2 applications is 3.3.2. While this specific package targets Vue 2, the project has evolved into the `@yzfe/vue-svgicon` package for Vue 3 compatibility, which is actively maintained. The core differentiator is its approach of pre-compiling SVGs into Vue components, which can lead to better performance by embedding optimized SVGs directly into the application bundle rather than loading them at runtime, offering a distinct advantage over runtime SVG loaders.","status":"maintenance","version":"3.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/MMF-FE/vue-svgicon","tags":["javascript","vue","vue2.0","svg","icon","svgicon","typescript"],"install":[{"cmd":"npm install vue-svgicon","lang":"bash","label":"npm"},{"cmd":"yarn add vue-svgicon","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-svgicon","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Vue 2 applications.","package":"vue","optional":false},{"reason":"Required peer dependency for compiling Vue 2 templates, especially when using single file components.","package":"vue-template-compiler","optional":false}],"imports":[{"note":"This is the default export used to register the global component via `Vue.use()`. For CommonJS, `const SvgIcon = require('vue-svgicon')` is appropriate.","wrong":"import { SvgIcon } from 'vue-svgicon'","symbol":"SvgIcon","correct":"import SvgIcon from 'vue-svgicon'"},{"note":"The programmatic build API is located in a deep path within the package and is a default export from that specific module.","wrong":"import { build } from 'vue-svgicon'","symbol":"build","correct":"import build from 'vue-svgicon/dist/lib/build'"},{"note":"Generated icon files directly register themselves globally with the `vue-svgicon` plugin upon import; they do not export a component directly. The 'icons/' path is a common convention but depends on your `vsvg` output target.","wrong":"import MyIcon from 'icons/my-icon'","symbol":"Generated Icon Registration","correct":"import 'icons/my-icon'"}],"quickstart":{"code":"/* src/main.js */\nimport Vue from 'vue'\nimport App from './App.vue'\nimport SvgIcon from 'vue-svgicon'\n\n// Register the SvgIcon component globally\nVue.use(SvgIcon, {\n  tagName: 'svgicon' // default tag name\n})\n\n// Inject global CSS for svg-icon styling (highly recommended).\n// In a real project, this would typically be in a global CSS file or imported via a bundler.\nconst globalSvgIconCss = `\n.svg-icon {\n    display: inline-block;\n    width: 16px;\n    height: 16px;\n    color: inherit;\n    vertical-align: middle;\n    fill: none;\n    stroke: currentColor;\n}\n.svg-fill {\n    fill: currentColor;\n    stroke: none;\n}\n`;\nconst style = document.createElement('style');\nstyle.textContent = globalSvgIconCss;\ndocument.head.appendChild(style);\n\nnew Vue({\n  el: '#app',\n  render: h => h(App)\n})\n\n/* App.vue */\n<template>\n  <div id=\"app\">\n    <h1>My App</h1>\n    <!-- The 'vue' icon must be generated first and imported -->\n    <svgicon name=\"vue\" width=\"50\" height=\"50\" color=\"#42b983 #35495e\"></svgicon>\n    <p>See console for icon generation instructions.</p>\n  </div>\n</template>\n\n<script>\n// Make sure 'icons/vue' path matches your generated icon directory.\n// This assumes 'src/icons' is where 'vsvg' outputs files, and you have configured Webpack\n// or similar to resolve 'icons' as an alias to 'src/icons'.\nimport 'icons/vue' \n\nexport default {\n  name: 'App',\n}\n</script>\n\n\n// --- Icon Generation (run these commands in your project root before dev server) ---\n// 1. Install vue-svgicon globally for the `vsvg` command:\n// npm install -g vue-svgicon \n// \n// 2. Create a directory for your source SVGs (e.g., static/svg/src):\n// mkdir -p static/svg/src \n// \n// 3. Create a sample SVG file (e.g., static/svg/src/vue.svg):\n// echo '<svg viewBox=\"0 0 200 200\"><circle cx=\"100\" cy=\"100\" r=\"80\" fill=\"#42b983\" /></svg>' > static/svg/src/vue.svg\n// \n// 4. Generate the icon components into your target directory (e.g., src/icons):\n// vsvg -s ./static/svg/src -t ./src/icons \n","lang":"javascript","description":"This quickstart demonstrates how to register the `vue-svgicon` component in a Vue 2 application, include essential global CSS for styling, and use a generated SVG icon within a component. It also provides the necessary command-line steps to generate a sample 'vue.svg' icon from a source SVG file."},"warnings":[{"fix":"Adjust your CSS selectors or JavaScript code to use the new '_' separator. Alternatively, you can customize the separator using the `--idSP` option during icon generation if strict backward compatibility is required.","message":"Version 3.0.0 introduced a breaking change by altering the default ID separator for generated SVG elements from '-' to '_'. If your project relied on the previous ID format for direct CSS targeting or JavaScript manipulation, your selectors will need updating.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"For Vue 3 development, install `@yzfe/vue-svgicon` and its ecosystem tools (e.g., `vite-plugin-svgicon` for Vite or `@yzfe/vue-cli-plugin-svgicon` for Vue CLI) and adapt your codebase accordingly. Do not use `vue-svgicon` v3.x in Vue 3 projects.","message":"The `vue-svgicon` package (v3.x) is explicitly designed for Vue 2.x applications and is not compatible with Vue 3. For new or migrating Vue 3 projects, you must switch to the `@yzfe/vue-svgicon` package, which is the actively maintained Vue 3 counterpart.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure the recommended CSS snippet (or a customized version based on your needs) is included in your global stylesheets. Refer to the `vue-svgicon` documentation for the 'recommended css code for vue-svgicon'.","message":"The `svgicon` component fundamentally relies on global CSS rules for its proper display, sizing, and styling (e.g., `display: inline-block`, `width`, `height`, `fill`, `stroke`). Without these essential styles, icons may not render visibly or correctly.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Use the command `vsvg -s /path/to/svg/source -t /path/for/generated/components --ext ts` to ensure TypeScript definition files are generated alongside the icon components. Verify your `tsconfig.json` is configured to correctly handle these generated `.ts` or `.d.ts` files.","message":"When using the `vsvg` command or its programmatic API, if you intend to generate TypeScript files for your icon components, you must explicitly set the `--ext` flag to `ts`. Otherwise, JavaScript files will be generated by default.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"First, ensure you have executed the `vsvg` command to generate your SVG icon components. Second, verify that the import statement for your specific icon (e.g., `import 'icons/my-icon'`) is correct and that the `name` prop on your `<svgicon>` component (e.g., `<svgicon name='my-icon'></svgicon>`) exactly matches the icon's original filename (without the extension).","cause":"The icon component's data was not properly registered. This typically occurs when the generated icon file has not been imported, or the `name` prop provided to the `<svgicon>` component does not precisely match a registered icon.","error":"Error in render: \"TypeError: Cannot read property 'data' of undefined\" or 'Cannot find icon name: [icon-name]'"},{"fix":"Add the recommended global CSS rules for `.svg-icon`, `.svg-fill`, `.svg-up`, etc., to your project's main stylesheet. Consult the `vue-svgicon` documentation's 'recommended css code for vue-svgicon' section for the exact styles.","cause":"The most frequent cause for this issue is the omission or incorrect application of the required global CSS for the `svg-icon` class. The component relies heavily on these styles for fundamental rendering properties such as `display`, `width`, and `height`.","error":"Icons appear as broken images or do not display at all in the browser, with no visible console errors."},{"fix":"Double-check the import path for the programmatic `build` function: `import build from 'vue-svgicon/dist/lib/build'`. Ensure that `vue-svgicon` is correctly installed in your `node_modules` directory and that your bundler's module resolution configuration is correctly set up to find deep imports within packages.","cause":"This error indicates that your module resolver cannot locate the programmatic `build` function. This could be due to an incorrect import path or an issue with package installation.","error":"Module not found: Error: Can't resolve 'vue-svgicon/dist/lib/build' in '[your-project-path]'"}],"ecosystem":"npm"}