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:
|
35 | 1. Use axios instance if provided
|
36 | 2. Use fetch if fetch options are provided
|
37 | 3. Use window.axios if exists
|
38 | 4. 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
|
88 | const app = Vue.createApp({ /* App component */ });
|
89 |
|
90 | // register Vue component into Vue app
|
91 | app.component("svg-inline", VueSvgInlineComponent);
|
92 |
|
93 | // mount Vue app
|
94 | app.mount("#app");
|
95 | ```
|
96 |
|
97 | ### [Vite][vite]
|
98 |
|
99 | ```javascript
|
100 | // import createApp from Vue
|
101 | import { createApp } from "vue";
|
102 |
|
103 | // import Vue component
|
104 | import VueSvgInlineComponent from "vue-svg-inline-component";
|
105 |
|
106 | // initialize Vue app
|
107 | const app = createApp({ /* App component */ });
|
108 |
|
109 | // register Vue component into Vue app
|
110 | app.component("svg-inline", VueSvgInlineComponent);
|
111 |
|
112 | // mount Vue app
|
113 | app.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`:**
|
179 | SVG file URL.
|
180 | Default value: `null`
|
181 |
|
182 | * **`tag`:**
|
183 | Tag 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.
|
185 | Default value: `"div"`
|
186 |
|
187 | * **`attributes`:**
|
188 | Attributes for wrapper element defined by `tag`.
|
189 | ⚠ If `tag` is set to `null` or `""` (empty string), `attributes` (see above) are ignored.
|
190 | Default value: `{ class: PACKAGE_NAME }`
|
191 |
|
192 | * **`cache`:**
|
193 | Response 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).
|
195 | Default value: `true`
|
196 |
|
197 | * **`fetchOptions`:**
|
198 | User-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.
|
200 | Default value: `null`
|
201 |
|
202 | * **`transformFunction`:**
|
203 | User-defined transform function for fetched SVG files. This function will be supplied with fetched SVG file, `transformFunctionOptions` (see below) and component props.
|
204 | Example: `(svg, options, props) => svg;`
|
205 | Default value: `null`
|
206 |
|
207 | * **`transformFunctionOptions`:**
|
208 | User-defined options for `transformFunction` (see above).
|
209 | Default value: `null`
|
210 |
|
211 | * **`emitUpdates`:**
|
212 | Enables emitting update events.
|
213 | Default value: `false`
|
214 |
|
215 | * **`emitErrors`:**
|
216 | Enables emitting error events.
|
217 | Default value: `false`
|
218 |
|
219 | * **`logErrors`:**
|
220 | Enables automatic logging of error events.
|
221 | Default value: `true`
|
222 |
|
223 | ### Overrides
|
224 |
|
225 | Default value of props could be overwritten as follows:
|
226 |
|
227 | ```javascript
|
228 | VueSvgInlineComponent.props.tag.default = "span";
|
229 | VueSvgInlineComponent.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`:**
|
238 | Fired each time component is updated. Updated SVG is passed as first argument.
|
239 |
|
240 | * **`error`:**
|
241 | Fired 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
|