{"id":15281,"library":"vue-svg-loader","title":"Vue SVG Loader","description":"`vue-svg-loader` is a Webpack loader designed to transform SVG files directly into functional Vue components, allowing developers to easily embed, style, and dynamically manipulate SVG assets within their Vue applications. The current stable version is 0.16.0, which primarily supports Vue 2 projects. However, version 0.17.0 is actively being developed in beta, with a strong focus on introducing robust Vue 3 compatibility. While its release cadence has historically been somewhat sporadic, recent activity indicates renewed development efforts, particularly for Vue 3. Key differentiators include its seamless integration into the Vue build process, automatic SVGO optimization (with an option to disable it), and the generation of functional components utilizing ESM exports since version 0.11.0, which contributes to better performance and tree-shaking capabilities.","status":"active","version":"0.16.0","language":"javascript","source_language":"en","source_url":"https://github.com/visualfanatic/vue-svg-loader","tags":["javascript","vue-svg-loader","svg","svgo","loader","webpack","vue"],"install":[{"cmd":"npm install vue-svg-loader","lang":"bash","label":"npm"},{"cmd":"yarn add vue-svg-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-svg-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Vue 2 projects; it's used internally to compile the SVG into a renderable Vue component.","package":"vue-template-compiler","optional":false}],"imports":[{"note":"Since v0.11.0, generated components use ESM exports, making `import` the idiomatic and recommended way to bring SVG components into your Vue files, leveraging Webpack's tree-shaking capabilities.","wrong":"const MyIcon = require('./assets/my-icon.svg');","symbol":"SVG Component Import","correct":"import MyIcon from './assets/my-icon.svg';"},{"note":"When combining with `vue-loader` for single-file components or when using `vue-svg-loader` to produce a Vue component, `vue-loader` often needs to process the output from `vue-svg-loader`. The order in the `use` array matters: `vue-svg-loader` should typically run first if `vue-loader` is processing its output.","wrong":"{ test: /\\.svg$/, loader: 'vue-svg-loader' }","symbol":"Webpack Loader Configuration","correct":"{ test: /\\.svg$/, use: ['vue-loader', 'vue-svg-loader'] }"},{"note":"Webpack loader options must always be nested under an `options` property within the loader rule. Direct properties like `svgo` on the rule object will be ignored or cause errors.","wrong":"{ loader: 'vue-svg-loader', svgo: { plugins: [{ removeViewBox: false }] } }","symbol":"Loader Options Configuration","correct":"{ loader: 'vue-svg-loader', options: { svgo: { plugins: [{ removeViewBox: false }] } } }"}],"quickstart":{"code":"import Vue from 'vue';\nimport App from './App.vue';\nimport TestIcon from './assets/test.svg';\n\n// webpack.config.js (excerpt)\n// module.exports = {\n//   module: {\n//     rules: [\n//       { test: /\\.vue$/, loader: 'vue-loader' },\n//       { test: /\\.js$/, loader: 'babel-loader' },\n//       { test: /\\.svg$/, use: ['vue-loader', 'vue-svg-loader'] },\n//     ],\n//   },\n//   resolve: {\n//     extensions: ['.js', '.vue', '.json', '.svg']\n//   }\n// };\n\n// App.vue\n<template>\n  <div id=\"app\">\n    <h1>Welcome to Vue SVG Loader Example</h1>\n    <p>Here's a dynamically styled SVG icon:</p>\n    <TestIcon class=\"my-icon\" :width=\"100\" :height=\"100\" />\n    <p>Another icon, with default sizing:</p>\n    <OtherIcon />\n  </div>\n</template>\n\n<script>\nimport OtherIcon from './assets/other.svg';\n\nexport default {\n  name: 'App',\n  components: {\n    TestIcon, // Register the imported SVG as a component\n    OtherIcon\n  }\n}\n</script>\n\n<style>\n.my-icon {\n  fill: blueviolet;\n  stroke: darkblue;\n  stroke-width: 2px;\n  transition: all 0.3s ease;\n}\n.my-icon:hover {\n  fill: hotpink;\n  transform: scale(1.1);\n}\n</style>\n\nnew Vue({\n  render: h => h(App),\n}).$mount('#app');","lang":"javascript","description":"Demonstrates how to configure Webpack with `vue-svg-loader` and use an imported SVG file as a functional Vue component within a template, including basic styling."},"warnings":[{"fix":"Ensure your bundler (e.g., Webpack, Rollup) is configured to handle ESM modules correctly. Always use `import` statements for SVG components rather than `require()` for optimal compatibility and benefits.","message":"Since v0.11.0, generated SVG components now utilize ESM export format. This might require adjustments in older CommonJS-centric build environments or specific tooling configurations to ensure proper module resolution and effective tree-shaking.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"If you relied on `toString()` for asset path resolution, you will need to implement an alternative strategy, such as using `file-loader` in a separate rule for SVGs where you need the path, or manually managing asset paths.","message":"The `toString()` method was removed from the SVG component definition in v0.6.0. This means you can no longer retrieve the absolute path of an imported SVG file by calling `MyIcon.toString()` on the imported component.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Consult the `svgo` documentation for the version bundled with `vue-svg-loader` and update your `svgo` options in `webpack.config.js` accordingly. As a temporary measure or if you don't need optimization, set `svgo: false` to disable it.","message":"SVGO configuration options have changed across different versions of `svgo` (e.g., v1.0.4 in v0.5.0, v1.1.1 in v0.10.0). Providing outdated or incorrect `svgo` options in `vue-svg-loader` config can lead to errors or unexpected SVG output.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"For Vue 2 projects, ensure `vue-template-compiler` is installed and compatible with your Vue version. For Vue 3, consider using `vite-plugin-svg` or await the stable release of `vue-svg-loader` v0.17.0 for robust Vue 3 support.","message":"The current stable release (v0.16.0) is primarily designed for Vue 2 applications and requires `vue-template-compiler@^2.0.0` as a peer dependency. Vue 3 support is being developed in the `0.17.0-beta` branch and is not yet considered stable for production use.","severity":"gotcha","affected_versions":"*"},{"fix":"Install `vue-template-compiler` explicitly: `npm install vue-template-compiler --save-dev`. Verify that its version matches the major version of your `vue` package.","message":"`vue-svg-loader` has a peer dependency on `vue-template-compiler` for Vue 2 projects, typically requiring a version compatible with your installed `vue` package (e.g., `^2.0.0`). Failure to install this dependency or installing an incompatible version will result in build errors.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Add or correct the `vue-svg-loader` rule in your `webpack.config.js` to specifically target `.svg` files, ensuring it's applied before any generic asset loaders that might just copy the file.","cause":"Webpack is encountering an SVG file but does not have a rule configured to process it with `vue-svg-loader` or another appropriate loader.","error":"Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file."},{"fix":"Install the `vue-template-compiler` package: `npm install vue-template-compiler --save-dev`. Ensure its version is compatible with your Vue 2 installation.","cause":"The required peer dependency `vue-template-compiler` is missing from your project's `node_modules` in a Vue 2 application.","error":"Cannot find module 'vue-template-compiler' or its corresponding type declarations."},{"fix":"Review the `svgo` documentation for the version bundled with `vue-svg-loader` and update your `svgo` options within `webpack.config.js`. You can also try setting `svgo: false` in the loader options to temporarily disable SVGO.","cause":"The `svgo` options provided to `vue-svg-loader` in your Webpack configuration are incorrect, malformed, or deprecated due to updates in the underlying `svgo` library.","error":"TypeError: Cannot read properties of undefined (reading 'someSvgoOption') OR Invalid SVGO config"},{"fix":"Ensure the imported SVG (e.g., `import MyIcon from './my-icon.svg';`) is explicitly listed in the `components` option of your Vue component (e.g., `components: { MyIcon }`) and used with the correct casing in the template (e.g., `<MyIcon />`).","cause":"The imported SVG component is not correctly registered within your Vue component's `components` option, or there's a mismatch in the component's name/casing between the `import` and its usage in the template.","error":"[Vue warn]: Failed to resolve component: MyIcon"}],"ecosystem":"npm"}