vue-svgicon

library3.3.2jsnpmunverified

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.

web-framework

npm install vue-svgicon

github ↗package ↗

INSTALL

IMPORT

SIG · VUE-SVGICON

vue-svgicon

web-frameworkjavascriptv3.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SvgIcon

✓ import SvgIcon from 'vue-svgicon'

✗ 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

✓ import build from 'vue-svgicon/dist/lib/build'

✗ import { build } from 'vue-svgicon'

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

✓ import 'icons/my-icon'

✗ import MyIcon from '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.

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

vsvg --version

Debug

Known issues

breakingVersion 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.

affects: >=3.0.0

breakingThe `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.

affects: >=3.0.0

gotchaThe `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'.

affects: >=3.0.0

gotchaWhen 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.

affects: >=3.0.0

Errors

Common errors & fixes

Error in render: "TypeError: Cannot read property 'data' of undefined" or 'Cannot find icon name: [icon-name]'

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.

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]'

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.

Upgrade

Version history

3.3.2latest on npm

Audit

Dependencies

vuerequiredRequired peer dependency for Vue 2 applications.

vue-template-compilerrequiredRequired peer dependency for compiling Vue 2 templates, especially when using single file components.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/MMF-FE/vue-svgicon ↗

packagehttps://www.npmjs.com/package/vue-svgicon ↗