vue-svg-inline-component

Vue component for inline use of SVG files.

⚠ Compatible only with Vue@3.

⚠ SVG files should be optimized beforehand (e.g.: using SVGO or SVGOMG).

Planned features for 1.0.0 release

• [ ] Validate SVG / ~~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)
• [x] Optionally remove wrapper element - v0.1.0
• [x] Transform function - v0.1.0
• [x] Default props overrides
• [ ] ~~Optionally remove SVG before each fetch request~~ Can be achieved manually by setting svg to null and via nextTick() setting to desired value
• [x] Fetch options - v0.1.0
• [ ] Axios support
• [x] Emits / Events - v0.1.0
• [x] Basic caching - v0.1.0
• [ ] Persistent caching with invalidation mechanism / versioning
• [ ] Lazy loading (intersection observer + template ref)
• [ ] ~~Placeholder image / element~~ Can be achieved manually by listening to first update event
• [ ] SVG sprites (if not fetch options and not transform function)
• [ ] .d.ts / tsc
• [ ] Analyze transpilled version and tune browserslist / remove modern build

Axios integration details:

1. Use axios instance if provided
2. Use fetch if fetch options are provided
3. Use window.axios if exists
4. Use fetch

Table of contents

• Installation
• Usage
• Configuration
• Examples

Installation

npm

$ npm install vue-svg-inline-component

yarn

$ yarn add vue-svg-inline-component

unpkg

<script src="https://unpkg.com/vue-svg-inline-component"></script>

<!-- or if you target only modern browsers, you can use modern build, which is way smaller in size -->
<script src="https://unpkg.com/vue-svg-inline-component/dist/vue-svg-inline-component-modern.min.js"></script>

jsDelivr

<script src="https://cdn.jsdelivr.net/npm/vue-svg-inline-component"></script>

<!-- or if you target only modern browsers, you can use modern build, which is way smaller in size -->
<script src="https://cdn.jsdelivr.net/npm/vue-svg-inline-component/dist/vue-svg-inline-component-modern.min.js"></script>

Usage

Browser

// initialize Vue app
const app = Vue.createApp({ /* App component */ });

// register Vue component into Vue app
app.component("svg-inline", VueSvgInlineComponent);

// mount Vue app
app.mount("#app");

Vite

// import createApp from Vue
import { createApp } from "vue";

// import Vue component
import VueSvgInlineComponent from "vue-svg-inline-component";

// initialize Vue app
const app = createApp({ /* App component */ });

// register Vue component into Vue app
app.component("svg-inline", VueSvgInlineComponent);

// mount Vue app
app.mount("#app");

Configuration

Default props

{
	source: {
		type: String,
		required: true,
		default: null,
		validator: validateSvgFilename
	},
	tag: {
		type: String,
		required: false,
		default: "div"
	},
	attributes: {
		type: Object,
		required: false,
		default: DEFAULT_ATTRIBUTES
	},
	cache: {
		type: Boolean,
		required: false,
		default: true
	},
	fetchOptions: {
		type: Object,
		required: false,
		default: null
	},
	transformFunction: {
		type: Function,
		required: false,
		default: null
	},
	transformFunctionOptions: {
		// type: any,
		required: false,
		default: null
	},
	emitUpdates: {
		type: Boolean,
		required: false,
		default: false
	},
	emitErrors: {
		type: Boolean,
		required: false,
		default: false
	},
	logErrors: {
		type: Boolean,
		required: false,
		default: true
	}
}

Explanation

• source:
  SVG file URL.
  Default value: null

• tag:
  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.
  ⚠ If tag is set to null or "" (empty string), attributes (see below) are ignored.
  Default value: "div"

• attributes:
  Attributes for wrapper element defined by tag.
  ⚠ If tag is set to null or "" (empty string), attributes (see above) are ignored.
  Default value: { class: PACKAGE_NAME }

• cache:
  Response from each SVG file requests will be stored in global variable and will be re-used on all consecutive requests.
  ⚠ Cache is not persistent between page reloads (yet).
  Default value: true

• fetchOptions:
  User-defined options object for fetch.
  ⚠ If fetchOptions are set, cache (see above) is automatically disabled for this component instance.
  Default value: null

• transformFunction:
  User-defined transform function for fetched SVG files. This function will be supplied with fetched SVG file, transformFunctionOptions (see below) and component props.
  Example: (svg, options, props) => svg;
  Default value: null

• transformFunctionOptions:
  User-defined options for transformFunction (see above).
  Default value: null

• emitUpdates:
  Enables emitting update events.
  Default value: false

• emitErrors:
  Enables emitting error events.
  Default value: false

• logErrors:
  Enables automatic logging of error events.
  Default value: true

Overrides

Default value of props could be overwritten as follows:

VueSvgInlineComponent.props.tag.default = "span";
VueSvgInlineComponent.props.attributes.default = { class: "my-inline-svg" };

Notice

⚠ Do not try to override other value then default in prop definition, as it can result in component not working correctly.

Events

• update:
  Fired each time component is updated. Updated SVG is passed as first argument.

• error:
  Fired each time error is detected. Error event is passed as first argument.

Examples

• Browser example
• Vite example

License

MIT