vue-svg-inline-plugin

Vue plugin for inline replacement of SVG images with actual content of SVG files.

⚠ Reactive Vue bindings won't be transfered to SVG replacement.

SVG files should be optimized beforehand (e.g.: using SVGO or SVGOMG).

Placeholder images should be optimized beforehand (e.g.: using pngquant or TinyPNG / TinyJPG).

Compatible with Vue@2 and Vue@3.

Table of contents:

• Installation
• Usage
• Directive
• Lazy loading
• Configuration
• Polyfills
• Examples

Installation

Package managers

• npm [package]:

  $ npm install vue-svg-inline-plugin --save

• yarn [package]:

  $ yarn add vue-svg-inline-plugin

Legacy browsers

• unpkg [package]:

  <script src="https://github.com/oliverfindl/vue-svg-inline-plugin/raw/master//unpkg.com/vue-svg-inline-plugin"></script>

• jsDelivr [package]:

  <script src="https://github.com/oliverfindl/vue-svg-inline-plugin/raw/master//cdn.jsdelivr.net/npm/vue-svg-inline-plugin"></script>

Modern browsers

This version is not transpiled and does not include any polyfills.

• unpkg [package]:

  <script src="https://github.com/oliverfindl/vue-svg-inline-plugin/raw/master//unpkg.com/vue-svg-inline-plugin/dist/vue-svg-inline-plugin-modern.min.js"></script>

• jsDelivr [package]:

  <script src="https://github.com/oliverfindl/vue-svg-inline-plugin/raw/master//cdn.jsdelivr.net/npm/vue-svg-inline-plugin/dist/vue-svg-inline-plugin-modern.min.js"></script>

Usage

Webpack based Vue projects (e.g.: Webpack or Vue CLI) and Vite projects

// Vue@2

// import basic Vue app
import Vue from "vue";
import App from "./App.vue";

// import Vue plugin
import VueSvgInlinePlugin from "vue-svg-inline-plugin";

// import polyfills for IE if you want to support it
import "vue-svg-inline-plugin/src/polyfills";

// use Vue plugin without options
Vue.use(VueSvgInlinePlugin);

// use Vue plugin with options
VueSvgInlinePlugin.install(Vue, {
    attributes: {
        data: [ "src" ],
        remove: [ "alt" ]
    }
});

// initialize and mount Vue app
new Vue({
    render: h => h(App),
}).$mount("#app");

// Vue@3

// import basic Vue app
import { createApp } from "vue";
import App from "./App.vue";

// import Vue plugin
import VueSvgInlinePlugin from "vue-svg-inline-plugin";

// import polyfills for IE if you want to support it
import "vue-svg-inline-plugin/src/polyfills";

// initialize Vue app
const app = createApp(App);

// use Vue plugin without options
app.use(VueSvgInlinePlugin);

// use Vue plugin with options
app.use(VueSvgInlinePlugin, {
    attributes: {
        data: [ "src" ],
        remove: [ "alt" ]
    }
});

// mount Vue app
app.mount("#app");

Browsers

// Vue@2

// use Vue plugin without options
Vue.use(VueSvgInlinePlugin);

// use Vue plugin with options
VueSvgInlinePlugin.install(Vue, {
    attributes: {
        data: [ "src" ],
        remove: [ "alt" ]
    }
});

// initialize and mount Vue app
new Vue({ /* options */ }).$mount("#app");

// Vue@3

// initialize Vue app
const app = Vue.createApp({ /* options */ });

// use Vue plugin without options
app.use(VueSvgInlinePlugin);

// use Vue plugin with options
app.use(VueSvgInlinePlugin, {
    attributes: {
        data: [ "src" ],
        remove: [ "alt" ]
    }
});

// mount Vue app
app.mount("#app");

Directive

Directive name can be changed via options.

v-svg-inline directive:

<img v-svg-inline class="icon" src="https://github.com/oliverfindl/vue-svg-inline-plugin/raw/master/images/example.svg" alt="example svg image" />

Replaces into:

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

v-svg-inline directive with sprite modifier:

~~⚠ Note, that for now, the viewBox property is not being applied on the <svg> link node.
This can cause issues when having icons differently sized in your UI.
For the most icon-systems, you can add a viewBox="0 0 24 24" by yourself onto the <img> node or use attributes.add option.~~

Fixed in version 2.1.0, use attributes.clone option.

<img v-svg-inline.sprite class="icon" src="https://github.com/oliverfindl/vue-svg-inline-plugin/raw/master/images/example.svg" alt="example svg image" />

Replaces into:

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

Lazy loading

This plugin supports lazy (down)loading of SVG files. To enable it, rename src attribute to data-src. Please also provide placeholder image, which should be located in src attribute to avoid broken image icons in browsers.

Configuration

Default options

{
    directive: {
        name: "v-svg-inline",
        spriteModifierName: "sprite"
    },
    attributes: {
        clone: [ "viewbox" ],
        merge: [ "class", "style" ],
        add: [ {
            name: "focusable",
            value: false
        }, {
            name: "role",
            value: "presentation"
        }, {
            name: "tabindex",
            value: -1
        } ],
        data: [],
        remove: [ "alt", "src", "data-src" ]
    },
    cache: {
        version: "<PACKAGE_VERSION>",
        persistent: true,
        removeRevisions: true
    },
    intersectionObserverOptions: {},
    axios: null,
    xhtml: false
}

Explanation

• directive.name:
  Defines directive name (lowercase string), which marks images you want to replace with inline SVGs.

• directive.spriteModifierName:
  Defines directive modifier name (lowercase string), which together with directive.name marks images you want to replace with inline SVGs using inline SVG sprites.

• attributes.clone:
  Array of attributes (lowercase strings) which should be cloned into SVG link node if using inline SVG sprites.

• attributes.merge:
  Array of attributes (lowercase strings) which should be merged.

• attributes.add:
  Array of attributes (objects with name (lowercase string) and value (string) properties), which should be added. If attribute already exists, it will be merged or skipped depending on attributes.merge option.

• attributes.data:
  Array of attributes (lowercase strings) which should be transformed into data-attributes. If data-attribute already exists, it will be merged or skipped depending on attributes.merge option.

• attributes.remove:
  Array of attributes (lowercase strings) which should be removed.

• cache.version:
  Defines cache version (lowercase string or number).

• cache.persistent:
  Boolean. Cache downloaded SVG files into local storage.

• cache.removeRevisions:
  Boolean. Remove previous cache revisions from local storage.

• intersectionObserverOptions:
  Intersection observer options object for processing image nodes. This option is not validated. Official documentation.

• axios:
  Axios instance with pre-configured options. If omitted, new axios instance (if axios available) will be created. Official documentation.

• xhtml:
  Boolean. In XHTML mode attribute minimization is forbidden. Empty attributes are filled with their names to be XHTML-compliant (e.g.: disabled="disabled").

Notices

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

• Attributes options are executed in this order: clone > merge > add > data > remove.

Polyfills

Required polyfills for IE:

• fetch polyfill or axios library
• IntersectionObserver polyfill

Examples

• Vue@2:
  • browser example
  • vue-cli example
  • webpack example
• Vue@3:
  • browser example
  • vite example
  • webpack example

License

MIT