@lgcnpm/vue-svg-inline-plugin
v2.2.5
Published
Vue plugin for inline replacement of SVG images with actual content of SVG files.
Downloads
8
Maintainers
Readme
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).
Table of contents:
Installation
Package managers
$ npm install vue-svg-inline-plugin --save
$ yarn add vue-svg-inline-plugin
Legacy browsers
<script src="//unpkg.com/vue-svg-inline-plugin"></script>
<script src="//cdn.jsdelivr.net/npm/vue-svg-inline-plugin"></script>
Modern browsers
This version is not transpiled and does not include any polyfills.
<script src="//unpkg.com/vue-svg-inline-plugin/dist/vue-svg-inline-plugin-modern.min.js"></script>
<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) 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="./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 aviewBox="0 0 24 24"
by yourself onto the<img>
node or useattributes.add
option.~~
Fixed in version 2.1.0, use
attributes.clone
option.
<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" 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 withdirective.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 onattributes.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 onattributes.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