vue-svg-inline-plugin

![version][npm]
![downloads][npm]
![license][mit]

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

> ⚠ Reactive [Vue][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][vue]@2 and [Vue][vue]@3.

---

Table of contents:

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

---

Installation

$3

* npm [[package][npm]]:
``bash
$ npm install vue-svg-inline-plugin --save
`

* yarn [package]:
`bash
$ yarn add vue-svg-inline-plugin
`

$3

* unpkg [package]:
`html

`

* jsDelivr [package]:
`html

`

$3

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

* unpkg [package]:
`html

`

* jsDelivr [package]:
`html

`

Usage

$3

`javascript
// 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");
`

`javascript
// 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");
`

$3

`javascript
// 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");
`

`javascript
// 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:

`html

`
Replaces into:
`xml




`

v-svg-inline directive with sprite modifier:
> ~~⚠ Note, that for now, the viewBox property is not being applied on the 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 node or use attributes.add option.~~

> Fixed in version 2.1.0, use attributes.clone option.

`html

`
Replaces into:
`xml











`

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

$3

`javascript
{
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: "",
persistent: true,
removeRevisions: true
},
intersectionObserverOptions: {},
axios: null,
xhtml: false
}
`

$3

* 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").

$3

* 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][vue]@2:
* browser example
* vue-cli example
* webpack example
* [Vue][vue]@3:
* browser example
* vite example
* webpack example

---

License

[MIT][mit]

[mit]: https://opensource.org/licenses/MIT
[npm]: https://www.npmjs.com/package/vue-svg-inline-plugin
[vue]: https://github.com/vuejs/vue
[vue-cli]: https://github.com/vuejs/vue-cli
[vite]: https://github.com/vitejs/vite
[webpack]: https://github.com/webpack/webpack