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 optimised beforehand (e.g.: using SVGO or SVGOMG).

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

Table of contents:

• Installation
• Usage
• Directives
• 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

Browsers

• unpkg [package]:

<script src="//unpkg.com/vue-svg-inline-plugin"></script>

• jsDelivr [package]:

<script src="//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="//unpkg.com/vue-svg-inline-plugin/dist/vue-svg-inline-plugin-modern.min.js"></script>

• jsDelivr [package]:

<script src="//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)

// import 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 without options
Vue.use(VueSvgInlinePlugin);

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

Browsers

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

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

Directives

Directive keyword can be changed via options.

v-svg-inline directive

Basic usage with v-svg-inline directive:

<img v-svg-inline class="icon" src="./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-sprite directive

Basic usage with v-svg-inline-sprite directive:

<img v-svg-inline-sprite class="icon" src="./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" 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

{
    directives: {
        inline: "v-svg-inline",
        inlineSprite: "v-svg-inline-sprite"
    },
    attributes: {
        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

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

• directives.inlineSprite
  Defines directive keyword (lowercase string), which marks images you want to replace with inline SVGs 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 mergeAttributes 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 mergeAttributes 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: merge > add > data > remove.

Polyfills

Required polyfills for IE:

• fetch polyfill or axios library
• IntersectionObserver polyfill

Examples

• browser example

• vue-cli example

• webpack example

License

MIT