Vue SVG Icon Component Tool

3.3.2 · maintenance · verified Sun Apr 19

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.

Common errors

```
Error in render: "TypeError: Cannot read property 'data' of undefined" or 'Cannot find icon name: [icon-name]'
```
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.

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).
```
Icons appear as broken images or do not display at all in the browser, with no visible console errors.
```
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`.

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.
```
Module not found: Error: Can't resolve 'vue-svgicon/dist/lib/build' in '[your-project-path]'
```
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.

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.

Warnings

breaking 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.
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.
breaking 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.
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.
gotcha 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.
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'.
gotcha 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.
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.

Install

npm install vue-svgicon npm
yarn add vue-svgicon yarn
pnpm add vue-svgicon pnpm

Imports

SvgIcon
wrong:
```
import { SvgIcon } from 'vue-svgicon'
```
correct:
```
import SvgIcon from 'vue-svgicon'
```
This is the default export used to register the global component via `Vue.use()`. For CommonJS, `const SvgIcon = require('vue-svgicon')` is appropriate.
build
wrong:
```
import { build } from 'vue-svgicon'
```
correct:
```
import build from 'vue-svgicon/dist/lib/build'
```
The programmatic build API is located in a deep path within the package and is a default export from that specific module.
Generated Icon Registration
wrong:
```
import MyIcon from 'icons/my-icon'
```
correct:
```
import 'icons/my-icon'
```
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.

Quickstart

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.

/* src/main.js */
import Vue from 'vue'
import App from './App.vue'
import SvgIcon from 'vue-svgicon'

// Register the SvgIcon component globally
Vue.use(SvgIcon, {
  tagName: 'svgicon' // default tag name
})

// Inject global CSS for svg-icon styling (highly recommended).
// In a real project, this would typically be in a global CSS file or imported via a bundler.
const globalSvgIconCss = `
.svg-icon {
    display: inline-block;
    width: 16px;
    height: 16px;
    color: inherit;
    vertical-align: middle;
    fill: none;
    stroke: currentColor;
}
.svg-fill {
    fill: currentColor;
    stroke: none;
}
`;
const style = document.createElement('style');
style.textContent = globalSvgIconCss;
document.head.appendChild(style);

new Vue({
  el: '#app',
  render: h => h(App)
})

/* App.vue */
<template>
  <div id="app">
    <h1>My App</h1>
    <!-- The 'vue' icon must be generated first and imported -->
    <svgicon name="vue" width="50" height="50" color="#42b983 #35495e"></svgicon>
    <p>See console for icon generation instructions.</p>
  </div>
</template>

<script>
// Make sure 'icons/vue' path matches your generated icon directory.
// This assumes 'src/icons' is where 'vsvg' outputs files, and you have configured Webpack
// or similar to resolve 'icons' as an alias to 'src/icons'.
import 'icons/vue' 

export default {
  name: 'App',
}
</script>


// --- Icon Generation (run these commands in your project root before dev server) ---
// 1. Install vue-svgicon globally for the `vsvg` command:
// npm install -g vue-svgicon 
// 
// 2. Create a directory for your source SVGs (e.g., static/svg/src):
// mkdir -p static/svg/src 
// 
// 3. Create a sample SVG file (e.g., static/svg/src/vue.svg):
// echo '<svg viewBox="0 0 200 200"><circle cx="100" cy="100" r="80" fill="#42b983" /></svg>' > static/svg/src/vue.svg
// 
// 4. Generate the icon components into your target directory (e.g., src/icons):
// vsvg -s ./static/svg/src -t ./src/icons

view raw JSON →