derrickpelletier / svg-injector

:syringe: Fast, caching, dynamic inline SVG DOM injection library.

svg-injector

A fast, caching, dynamic inline SVG DOM injection library.

Background

There are a number of ways to use SVG on a page (object, embed, iframe, img, CSS background-image) but to unlock the full potential of SVG, including full element-level CSS styling and evaluation of embedded JavaScript, the full SVG markup must be included directly in the DOM.

Wrangling and maintaining a bunch of inline SVG on your pages isn't anyone's idea of good time, so SVGInjector lets you work with simple tag elements and does the heavy lifting of swapping in the SVG markup inline for you.

Basic Usage

<div id="inject-me" data-src="icon.svg"></div>

import SVGInjector from '@tanem/svg-injector'

SVGInjector(document.getElementById('inject-me'))

Live Examples

• Basic Usage: Source | Sandbox
• API Usage: Source | Sandbox
• UMD Build (Development): Source | Sandbox
• UMD Build (Production): Source | Sandbox

API

Arguments

• elements - A single DOM element or array of elements, with src or data-src attributes defined, to inject.
• options - Optional An object containing the optional arguments defined below. Defaults to {}.
  • done(elementsLoaded) - Optional A callback which is called when all elements have been processed. elementsLoaded is the total number of elements loaded. Defaults to undefined.
  • each(err, svg) - Optional A callback which is called when each element is processed. svg is the newly injected SVG DOM element. Defaults to () => undefined.
  • evalScripts - Optional Run any script blocks found in the SVG. One of 'always', 'once', or 'never'. Defaults to 'never'.
  • renumerateIRIElements - Optional Boolean indicating if SVG IRI addressable elements should be renumerated. Defaults to true.

Example

<div class="inject-me" data-src="icon-one.svg"></div>
<div class="inject-me" data-src="icon-two.svg"></div>

import SVGInjector from '@tanem/svg-injector'

SVGInjector(document.getElementsByClassName('inject-me'), {
  done(elementsLoaded) {
    console.log(`injected ${elementsLoaded} elements`)
  },
  each(err, svg) {
    if (err) {
      throw err
    }
    console.log(`injected ${svg.outerHTML}`)
  },
  evalScripts: 'once',
  renumerateIRIElements: 'false'
})

Installation

$ npm install @tanem/svg-injector

There are also UMD builds available via unpkg:

• https://unpkg.com/@tanem/svg-injector/umd/svg-injector.development.js
• https://unpkg.com/@tanem/svg-injector/umd/svg-injector.production.min.js

Credits

This is a fork of a library originally developed by Waybury for use in iconic.js, part of the Iconic icon system.

License

MIT