UNPKG

7.87 kBMarkdownView Raw
1# vue-svg-inline-component
2
3[![version](https://img.shields.io/npm/v/vue-svg-inline-component.svg?style=flat)][npm]
4[![downloads](https://img.shields.io/npm/dt/vue-svg-inline-component.svg?style=flat)][npm]
5[![license](https://img.shields.io/npm/l/vue-svg-inline-component.svg?style=flat)][mit]
6[![paypal](https://img.shields.io/badge/donate-paypal-blue.svg?colorB=0070ba&style=flat)](https://paypal.me/oliverfindl)
7
8[Vue][vue3] component for inline use of SVG files.
9
10> ⚠ Compatible only with [Vue@3][vue3].
11
12> ⚠ SVG files should be optimized beforehand (e.g.: using [SVGO](https://www.npmjs.com/package/svgo) or [SVGOMG](https://jakearchibald.github.io/svgomg/)).
13
14---
15
16## Planned features for 1.0.0 release
17
18- [ ] Validate SVG / ~~[is-svg](https://www.npmjs.com/package/is-svg)~~ Bloats modern build with ~20% increase in size, also can be validated manually with transform function (should be enforced if `tag` is set to falsy value)
19- [x] Optionally remove wrapper element - [v0.1.0][v0.1.0]
20- [x] Transform function - [v0.1.0][v0.1.0]
21- [x] Default props overrides
22- [ ] ~~Optionally remove SVG before each fetch request~~ Can be achieved manually by setting svg to `null` and via `nextTick()` setting to desired value
23- [x] [Fetch options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options) - [v0.1.0][v0.1.0]
24- [ ] [Axios][axios] support
25- [x] Emits / Events - [v0.1.0][v0.1.0]
26- [x] Basic caching - [v0.1.0][v0.1.0]
27- [ ] Persistent caching with invalidation mechanism / versioning
28- [ ] Lazy loading ([intersection observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) + [template ref](https://v3.vuejs.org/guide/component-template-refs.html))
29- [ ] ~~Placeholder image / element~~ Can be achieved manually by listening to first `update` event
30- [ ] SVG sprites (if not fetch options and not transform function)
31- [ ] [.d.ts](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html) / [tsc](https://www.typescriptlang.org/docs/handbook/intro.html)
32- [ ] Analyze transpilled version and tune browserslist / remove modern build
33
34[Axios][axios] integration details:
351. Use axios instance if provided
362. Use fetch if fetch options are provided
373. Use window.axios if exists
384. Use fetch
39
40[v0.1.0]: https://github.com/oliverfindl/vue-svg-inline-component/releases/tag/v0.1.0
41[axios]: https://github.com/axios/axios
42
43---
44
45## Table of contents
46
47* [Installation](#installation)
48* [Usage](#usage)
49* [Configuration](#configuration)
50* [Examples](#examples)
51
52---
53
54## Installation
55
56### [npm][npm]
57```bash
58$ npm install vue-svg-inline-component
59```
60
61### [yarn][yarn]
62```bash
63$ yarn add vue-svg-inline-component
64```
65
66### [unpkg][unpkg]
67```html
68<script src="https://unpkg.com/vue-svg-inline-component"></script>
69
70<!-- or if you target only modern browsers, you can use modern build, which is way smaller in size -->
71<script src="https://unpkg.com/vue-svg-inline-component/dist/vue-svg-inline-component-modern.min.js"></script>
72```
73
74### [jsDelivr][jsdelivr]
75```html
76<script src="https://cdn.jsdelivr.net/npm/vue-svg-inline-component"></script>
77
78<!-- or if you target only modern browsers, you can use modern build, which is way smaller in size -->
79<script src="https://cdn.jsdelivr.net/npm/vue-svg-inline-component/dist/vue-svg-inline-component-modern.min.js"></script>
80```
81
82## Usage
83
84### Browser
85
86```javascript
87// initialize Vue app
88const app = Vue.createApp({ /* App component */ });
89
90// register Vue component into Vue app
91app.component("svg-inline", VueSvgInlineComponent);
92
93// mount Vue app
94app.mount("#app");
95```
96
97### [Vite][vite]
98
99```javascript
100// import createApp from Vue
101import { createApp } from "vue";
102
103// import Vue component
104import VueSvgInlineComponent from "vue-svg-inline-component";
105
106// initialize Vue app
107const app = createApp({ /* App component */ });
108
109// register Vue component into Vue app
110app.component("svg-inline", VueSvgInlineComponent);
111
112// mount Vue app
113app.mount("#app");
114```
115
116## Configuration
117
118### Default [props](https://v3.vuejs.org/guide/component-props.html)
119
120```javascript
121{
122 source: {
123 type: String,
124 required: true,
125 default: null,
126 validator: validateSvgFilename
127 },
128 tag: {
129 type: String,
130 required: false,
131 default: "div"
132 },
133 attributes: {
134 type: Object,
135 required: false,
136 default: DEFAULT_ATTRIBUTES
137 },
138 cache: {
139 type: Boolean,
140 required: false,
141 default: true
142 },
143 fetchOptions: {
144 type: Object,
145 required: false,
146 default: null
147 },
148 transformFunction: {
149 type: Function,
150 required: false,
151 default: null
152 },
153 transformFunctionOptions: {
154 // type: any,
155 required: false,
156 default: null
157 },
158 emitUpdates: {
159 type: Boolean,
160 required: false,
161 default: false
162 },
163 emitErrors: {
164 type: Boolean,
165 required: false,
166 default: false
167 },
168 logErrors: {
169 type: Boolean,
170 required: false,
171 default: true
172 }
173}
174```
175
176#### Explanation
177
178* **`source`:**
179SVG file URL.
180Default value: `null`
181
182* **`tag`:**
183Tag for wrapper element, in which will be SVG rendered. Can be set to `null` or `""` (empty string) if you don't want to use wrapper element, but bear in mind, this approach is more taxing on performance and is not recommended.
184⚠ If `tag` is set to `null` or `""` (empty string), `attributes` (see below) are ignored.
185Default value: `"div"`
186
187* **`attributes`:**
188Attributes for wrapper element defined by `tag`.
189⚠ If `tag` is set to `null` or `""` (empty string), `attributes` (see above) are ignored.
190Default value: `{ class: PACKAGE_NAME }`
191
192* **`cache`:**
193Response from each SVG file requests will be stored in global variable and will be re-used on all consecutive requests.
194⚠ Cache is not persistent between page reloads (yet).
195Default value: `true`
196
197* **`fetchOptions`:**
198User-defined options object for [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options).
199⚠ If `fetchOptions` are set, `cache` (see above) is automatically disabled for this component instance.
200Default value: `null`
201
202* **`transformFunction`:**
203User-defined transform function for fetched SVG files. This function will be supplied with fetched SVG file, `transformFunctionOptions` (see below) and component props.
204Example: `(svg, options, props) => svg;`
205Default value: `null`
206
207* **`transformFunctionOptions`:**
208User-defined options for `transformFunction` (see above).
209Default value: `null`
210
211* **`emitUpdates`:**
212Enables emitting update events.
213Default value: `false`
214
215* **`emitErrors`:**
216Enables emitting error events.
217Default value: `false`
218
219* **`logErrors`:**
220Enables automatic logging of error events.
221Default value: `true`
222
223### Overrides
224
225Default value of props could be overwritten as follows:
226
227```javascript
228VueSvgInlineComponent.props.tag.default = "span";
229VueSvgInlineComponent.props.attributes.default = { class: "my-inline-svg" };
230```
231
232#### Notice
233⚠ Do not try to override other value then default in prop definition, as it can result in component not working correctly.
234
235### Events
236
237* **`update`:**
238Fired each time component is updated. Updated SVG is passed as first argument.
239
240* **`error`:**
241Fired each time error is detected. Error event is passed as first argument.
242
243## Examples
244
245* [Browser example](https://github.com/oliverfindl/vue-svg-inline-component/tree/master/examples/browser)
246* [Vite example](https://github.com/oliverfindl/vue-svg-inline-component/tree/master/examples/vite)
247
248---
249
250## License
251
252[MIT][mit]
253
254[mit]: https://opensource.org/licenses/MIT
255[npm]: https://www.npmjs.com/package/vue-svg-inline-component
256[yarn]: https://yarnpkg.com/package/vue-svg-inline-component
257[unpkg]: https://www.unpkg.com/browse/vue-svg-inline-component/
258[jsdelivr]: https://www.jsdelivr.com/package/npm/vue-svg-inline-component
259[vue3]: https://github.com/vuejs/vue-next
260[vite]: https://github.com/vitejs/vite