@tanem/svg-injector

What is @tanem/svg-injector?

@tanem/svg-injector is an npm package that allows you to dynamically inject SVG files into the DOM. This can be useful for manipulating SVGs with CSS and JavaScript, improving accessibility, and optimizing performance.

What are @tanem/svg-injector's main functionalities?

Basic SVG Injection

This feature allows you to inject an SVG file into a specified DOM element. The SVG content will replace the content of the target element.

const SVGInjector = require('@tanem/svg-injector');

const mySVGElement = document.querySelector('#my-svg');
SVGInjector(mySVGElement);

Batch SVG Injection

This feature allows you to inject multiple SVG files into multiple DOM elements in a single call. This is useful for batch processing multiple SVGs at once.

const SVGInjector = require('@tanem/svg-injector');

const svgElements = document.querySelectorAll('.svg-inject');
SVGInjector(svgElements);

Callback Function

This feature allows you to specify a callback function that will be called after all SVGs have been injected. This can be useful for performing additional actions once the injection is complete.

const SVGInjector = require('@tanem/svg-injector');

const mySVGElement = document.querySelector('#my-svg');
SVGInjector(mySVGElement, {
  afterAll: (elementsLoaded) => {
    console.log(`${elementsLoaded.length} SVGs injected`);
  }
});

Other packages similar to @tanem/svg-injector

svg-injector

svg-injector is another popular package for injecting SVGs into the DOM. It offers similar functionality to @tanem/svg-injector but may have different API methods and options.

react-svg

react-svg is a React component for injecting SVGs into the DOM. It is specifically designed for use with React applications and offers a more React-friendly API compared to @tanem/svg-injector.

svg-inline-loader

svg-inline-loader is a Webpack loader that inlines SVGs into your JavaScript bundles. It offers a different approach to SVG injection by integrating directly into the build process.

README

svg-injector

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

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

table of contents

• why
• how
• basic example
• api
• full example
• codesandbox examples
• usage with react
• license

why

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 img tag elements (or other tag of your choosing) and does the heavy lifting of swapping in the SVG markup inline for you.

how

• Any DOM element, or array of elements, passed to SVGInjector with an SVG file src or data-src attribute will be replaced with the full SVG markup inline. The async loaded SVG is also cached so multiple uses of an SVG only requires a single server request.
• Any embedded JavaScript in the SVG will optionally be extracted, cached and evaluated.

:warning: The dynamic injection process uses AJAX calls to load SVG. If you are developing locally without running a local webserver, be aware that default browser security settings may block these calls.

basic example

Include the SVGInjector script on your page.

<script src="https://unpkg.com/@tanem/svg-injector/umd/svg-injector.min.js"></script>

Add some SVG img tags.

<img class="inject-me" src="image-one.svg">
<img class="inject-me" src="image-two.svg">

Inject 'em.

<script>
  // Elements to inject
  var mySVGsToInject = document.querySelectorAll('img.inject-me')

  // Do the injection
  SVGInjector(mySVGsToInject)
</script>

The img tags have now been replaced with the full SVG markup.

api

In addition to passing elements to inject, an options object and callback function can optionally be defined.

SVGInjector(elements, options, callback)

elements

A single DOM element or array of elements, with src or data-src attributes defined, to inject.

options

{
  evalScripts: [always|once|never],
  pngFallback: [PNG directory],
  each: [function],
  renumerateIRIElements: [true|false]
}

• evalScript - String

  Should we run any script blocks found in the SVG?

  • always - Run them every time.
  • once - [default] Only run scripts once for each SVG file, even if it is used on a page more than once.
  • [false|'never'] - Ignore scripts

• pngFallback - String

  The directory where fallback PNGs are located for use if the browser doesn't support SVG. This will look for a file with a .png extension matching the SVG filename defined in the src (or data-src).

  For additional flexibility, since you might be using a single SVG styled in multiple ways, you can also define per-element fallbacks by adding a data-fallback or data-png attribute to your img tags to define a unique PNG for each context. Refer to the Fallbacks example.

• each(error, svg) - function

  A function to call after each SVG is injected. If an error occurred it will be passed as the first parameter. Otherwise the first parameter will be null, and the second will be the newly injected SVG DOM element.

• renumerateIRIElements - boolean

  Should we renumerate all of the SVG IRI addressable elements?

  • true - [default] Renumerate.
  • false - Don't renumerate.

callback

A function to call once all the requested SVG elements have been injected. Receives a count of the total SVGs injected as a parameter.

full example

<img id="image-one" class="inject-me" data-src="image-one.svg">
<img id="image-two" class="inject-me" data-src="image-two.svg">

// Elements to inject
var mySVGsToInject = document.querySelectorAll('img.inject-me')

// Options
var injectorOptions = {
  evalScripts: 'once',
  pngFallback: 'assets/png',
  each: function(error, svg) {
    if (!error) {
      console.log('SVG injected: ' + svg.getAttribute('id'))
    }
  }
}

// Trigger the injection
SVGInjector(mySVGsToInject, injectorOptions, function(totalSVGsInjected) {
  // Callback after all SVGs are injected
  console.log('We injected ' + totalSVGsInjected + ' SVG(s)!')
})

codesandbox examples

• All the things
• Fallbacks
• Simple

usage with react

• react-svg

license

MIT