Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/oliverfindl/vue-svg-inline-plugin
Vue plugin for inline replacement of SVG images with actual content of SVG files.
https://github.com/oliverfindl/vue-svg-inline-plugin
inline javascript plugin sprites svg symbols vue vue-plugin vue-svg-inline-plugin vuejs
Last synced: 19 days ago
JSON representation
Vue plugin for inline replacement of SVG images with actual content of SVG files.
- Host: GitHub
- URL: https://github.com/oliverfindl/vue-svg-inline-plugin
- Owner: oliverfindl
- License: mit
- Created: 2019-11-11T19:27:09.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2022-11-08T22:04:27.000Z (about 2 years ago)
- Last Synced: 2024-10-05T21:17:15.886Z (about 1 month ago)
- Topics: inline, javascript, plugin, sprites, svg, symbols, vue, vue-plugin, vue-svg-inline-plugin, vuejs
- Language: JavaScript
- Size: 242 KB
- Stars: 33
- Watchers: 2
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# vue-svg-inline-plugin
[][npm]
[][npm]
[][mit]
[](https://paypal.me/oliverfindl)
[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](https://www.npmjs.com/package/svgo) or [SVGOMG](https://jakearchibald.github.io/svgomg/)).
> Placeholder images should be optimized beforehand (e.g.: using [pngquant](https://pngquant.org/) or [TinyPNG](https://tinypng.com/) / [TinyJPG](https://tinyjpg.com/)).
> Compatible with [Vue][vue]@2 and [Vue][vue]@3.
---
## Table of contents:
* [Installation](#installation)
* [Usage](#usage)
* [Directive](#directive)
* [Lazy loading](#lazy-loading)
* [Configuration](#configuration)
* [Polyfills](#polyfills)
* [Examples](#examples)
---
## Installation
### Package managers
* [npm](https://npmjs.com/) [[package][npm]]:
```bash
$ npm install vue-svg-inline-plugin --save
```
* [yarn](https://yarnpkg.com/en/) [[package](https://yarnpkg.com/en/package/vue-svg-inline-plugin)]:
```bash
$ yarn add vue-svg-inline-plugin
```
### Legacy browsers
* [unpkg](https://unpkg.com/) [[package](https://www.unpkg.com/browse/vue-svg-inline-plugin/)]:
```html
```
* [jsDelivr](https://jsdelivr.com/) [[package](https://www.jsdelivr.com/package/npm/vue-svg-inline-plugin)]:
```html
```
### Modern browsers
> This version is not transpiled and does not include any [polyfills](#polyfills).
* [unpkg](https://unpkg.com/) [[package](https://www.unpkg.com/browse/vue-svg-inline-plugin/)]:
```html
```
* [jsDelivr](https://jsdelivr.com/) [[package](https://www.jsdelivr.com/package/npm/vue-svg-inline-plugin)]:
```html
```
## Usage
### [Webpack][webpack] based [Vue][vue] projects (e.g.: [Webpack][webpack] or [Vue CLI][vue-cli]) and [Vite][vite] projects
```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");
```
### Browsers
```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](#configuration).
**`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](#configuration).~~
> Fixed in version 2.1.0, use [`attributes.clone` option](#configuration).
```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
### Default options
```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
}
```
### 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](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#Intersection_observer_options).
* **`axios`:**
Axios instance with pre-configured options. If omitted, new axios instance (if axios available) will be created. [Official documentation](https://github.com/axios/axios#creating-an-instance).
* **`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](https://github.com/github/fetch) polyfill or [axios](https://github.com/axios/axios) library
* [IntersectionObserver](https://github.com/w3c/IntersectionObserver) polyfill
## Examples
* [Vue][vue]@2:
* [browser example](https://github.com/oliverfindl/vue-svg-inline-plugin/tree/master/examples/browser-vue2)
* [vue-cli example](https://github.com/oliverfindl/vue-svg-inline-plugin/tree/master/examples/vue-cli-vue2)
* [webpack example](https://github.com/oliverfindl/vue-svg-inline-plugin/tree/master/examples/webpack-vue2)
* [Vue][vue]@3:
* [browser example](https://github.com/oliverfindl/vue-svg-inline-plugin/tree/master/examples/browser-vue3)
* [vite example](https://github.com/oliverfindl/vue-svg-inline-plugin/tree/master/examples/vite-vue3)
* [webpack example](https://github.com/oliverfindl/vue-svg-inline-plugin/tree/master/examples/webpack-vue3)
---
## 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