README

vue-svg-inline-loader

Webpack loader used for inline replacement of SVG images with actual content of SVG files in Vue projects.

Loader parses only HTML template format.

Loader has built-in SVGO support for SVG optimization.

Sprite option works only with Vue Single File Component approach.

Vue CLI

Vue 3 projects created via Vue CLI aren't built on top of Webpack, they use Vite (which is build on top of Rollup) instead. In this case, this loader won't work. Please take a look at vue-svg-inline-plugin, which works similar to this loader.

Notable changes

v2.1.0
- Added new option: cloneAttributes
v2.0.0
- Removed transpiled version
- Removed core-js@2 dependency
- Recreated all examples (except vanilla Webpack one) with up-to-date CLIs
v1.5.0
- Added new option: transformImageAttributesToVueDirectives
- Added new option: verbose
v1.4.4
- Updated order of attributes operations
v1.4.0
- Added new option: addTitle
- Fixed issue with lowercase-ing attribute values
v1.3.1
- Hotfixed issue with doubled attribute definitions on SVG node. This may introduce breaking changes for developers who used image definitions outside of template tag.
v1.3.0
- Added new option: addAttributes
v1.2.17
- Add example usage configuration for laravel-mix based projects
v1.2.16
- Added example for quasar based projects
v1.2.14
- Added example for gridsome based projects
v1.2.11
- Fixed a bug where original svg attributes were used by referencing svg rather than symbol itself. This may introduce breaking changes for developers who rely on this bugged behavior.
v1.2.6
- Modified default value of svgo option to preserve viewBox attribute
- Modified svgo option to accept true value as alias for default configuration
v1.2.5
- Modified svgo option to accept null or false value for disabling SVG optimization
v1.2.3
- Changed default value of md5 option to true
- Added examples for webpack, vue-cli and nuxt based projects
v1.2.0
- Upgraded Babel to version 7
- Refactored code to ES6 syntax
- Added new option: dataAttributes
- Options are now deep-merged
v1.1.3
- Added transpiled version of loader
v1.1.0
- Added new option: md5
v1.0.8
- Options structure changed, deprecated options still get parsed to new ones
v1.0.0
- Initial release based on my img-svg-inline-loader project

Install

Via npm [package]:

$ npm install vue-svg-inline-loader --save-dev

Via yarn [package]:

$ yarn add vue-svg-inline-loader --dev

Usage

With webpack - webpack.config.js (recommended):

// webpack

module.exports = {
    module: {
        rules: [
            {
                test: /\.vue$/,
                use: [
                    {
                        loader: "vue-loader",
                        options: { /* ... */ }
                    },
                    {
                        loader: "vue-svg-inline-loader",
                        options: { /* ... */ }
                    }
                ]
            }
        ]
    }
};

With vue-cli - vue.config.js:
With gridsome - gridsome.config.js:
With quasar - quasar.conf.js:

// vue-cli, gridsome, quasar

module.exports = {
    chainWebpack: config => {
        config.module
            .rule("vue")
            .use("vue-svg-inline-loader")
                .loader("vue-svg-inline-loader")
                .options({ /* ... */ });
    }
};

With nuxt - nuxt.config.js:
With quasar - quasar.conf.js:

// nuxt, quasar

module.exports = {
    build: {
        // use extend() method for nuxt
        // use extendWebpack() method for quasar
        extendWebpack(config, { isServer, isClient }) {
            config.module.rules.push({
                test: /\.vue$/,
                loader: "vue-svg-inline-loader",
                options: { /* ... */ }
            })
        }
    }
};

With laravel-mix - webpack.mix.js:

// laravel-mix

const mix = require("laravel-mix");

mix.override(config => {
    config.module.rules.push({
        test: /\.vue$/,
        use: [{
            loader: "vue-svg-inline-loader",
            options: { /* ... */ }
        }]
    })
});

Basic inline SVG usage with svg-inline keyword directive:

<img svg-inline class="icon" src="./images/example.svg" alt="example" />

Which replaces into:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="..." svg-inline role="presentation" focusable="false" tabindex="-1" class="icon">
    <path d="..."></path>
</svg>

Basic inline SVG sprite usage with svg-sprite keyword directive:

<img svg-inline svg-sprite class="icon" src="./images/example.svg" alt="example" />

Which replaces into:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="..." svg-inline svg-sprite role="presentation" focusable="false" tabindex="-1" class="icon">
    <use xlink:href="#svg-sprite-md5hash" href="#svg-sprite-md5hash"></use>
</svg>
<!-- ... -->
<!-- will get injected right before root closing tag in Vue component -->
<svg xmlns="http://www.w3.org/2000/svg" style="display: none !important;">
    <symbol id="svg-sprite-md5hash" xmlns="http://www.w3.org/2000/svg" viewBox="...">
        <path d="..."></path>
    </symbol>
    <!-- ... -->
</svg>

Notice

Loader won't parse any images with Vue bindings used as src attribute [more info].

If you need to preserve image tag (e.g. in comments), you can wrap it in hash (#) or triple backtick (```) characters.

Configuration

Default options:

{
    inline: {
        keyword: "svg-inline",
        strict: true
    },
    sprite: {
        keyword: "svg-sprite",
        strict: true
    },
    addTitle: false,
    cloneAttributes: ["viewbox"],
    addAttributes: {
        role: "presentation",
        focusable: false,
        tabindex: -1
    },
    dataAttributes: [],
    removeAttributes: ["alt", "src"],
    transformImageAttributesToVueDirectives: true,
    md5: true,
    xhtml: false,
    svgo: true,
/* value true for svgo option is alias for:
    svgo: {
        plugins: [
            {
                removeViewBox: false
            }
        ]
    },
*/
    verbose: false
}

Explanation:

inline.keyword:
Defines keyword, which marks images you want to replace with inline SVG. Keyword has to be wrapped with whitespace characters (e.g. space). In case of some conflicts, you can also use data version of your keyword (e.g. data-keyword).
inline.strict:
In strict mode loader replaces only images with defined keyword. If strict mode is disabled, loader replaces all images.
sprite.keyword:
Defines keyword, which marks images you want to replace with inline SVG using inline sprites. Keyword has to be wrapped with whitespace characters (e.g. space). In case of some conflicts, you can also use data version of your keyword (e.g. data-keyword).
sprite.strict:
In strict mode loader replaces only images with defined keyword. If strict mode is disabled, loader replaces all images.
addTitle:
Transform image alt attribute into SVG title tag, if not defined (removed with SVGO by default). This option has no effect while using inline SVG sprites.
cloneAttributes:
Array of attributes which will be cloned into SVG link node while using inline SVG sprites.
addAttributes:
Object of attributes which will be added.
dataAttributes:
Array of attributes which will be renamed to data-attributes.
removeAttributes:
Array of attributes which will be removed.
transformImageAttributesToVueDirectives:
Transforms all non-Vue image tag attributes via Vue v-bind directive. With this option enabled, Vue will handle merge / replace attributes, that are present on both resources - image tag and SVG tag. This might cause issues, when using Vue bindings on image tag attribute, that is also present on SVG tag (e.g.: class attribute). Please use verbose option for local debugging before submitting new issue.
md5:
Use md5-encoded resource path as ID for inline SVG sprites instead of plaintext. Set it to false only for development purposes.
xhtml:
In XHTML mode attribute minimization is forbidden. Empty attributes are filled with their names to be XHTML-compliant (e.g. disabled="disabled").
svgo:
Pass SVGO configuration object (documentation can be found here) or true for default configuration. Pass null or false to disable SVG optimization.
verbose:
Will print image tag, SVG tag and modified SVG tag (with attributes from image tag) for debugging purposes.

Notices

User-defined options are deep-merged with default options. Arrays are not concatenated.

Examples

License

MIT

Usage no npm install needed!