@tanem/svg-injector
v10.1.68
Published
Fast, caching, dynamic inline SVG DOM injection library.
Downloads
735,473
Maintainers
Readme
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'))
Avoiding XSS
Be careful when injecting arbitrary third-party SVGs into the DOM, as this opens the door to XSS attacks. If you must inject third-party SVGs, it is highly recommended to sanitize the SVG before injecting. The following example uses DOMPurify to strip out attributes and tags that can execute arbitrary JavaScript. Note that this can alter the behavior of the SVG.
import { SVGInjector } from '@tanem/svg-injector'
import DOMPurify from 'dompurify'
SVGInjector(document.getElementById('inject-me'), {
beforeEach(svg) {
DOMPurify.sanitize(svg, {
IN_PLACE: true,
USE_PROFILES: { svg: true, svgFilters: true },
})
},
})
Live Examples
- Basic Usage: Source | Sandbox
- API Usage: Source | Sandbox
- MooTools: Source | Sandbox
- UMD Build (Development): Source | Sandbox
- UMD Build (Production): Source | Sandbox
API
Arguments
elements
- A single DOM element or array of elements, withsrc
ordata-src
attributes defined, to inject.options
- Optional An object containing the optional arguments defined below. Defaults to{}
.afterAll(elementsLoaded)
- Optional A callback which is called when all elements have been processed.elementsLoaded
is the total number of elements loaded. Defaults to() => undefined
.afterEach(err, svg)
- Optional A callback which is called when each element is processed.svg
is the newly injected SVG DOM element. Defaults to() => undefined
.beforeEach(svg)
- Optional A callback which is called just before each SVG element is added to the DOM.svg
is the SVG DOM element which is about to be injected. Defaults to() => undefined
.cacheRequests
- Optional Use request cache. Defaults totrue
.evalScripts
- Optional Run any script blocks found in the SVG. One of'always'
,'once'
, or'never'
. Defaults to'never'
.httpRequestWithCredentials
- Optional Boolean that indicates whether or not cross-site Access-Control requests should be made using credentials. Defaults tofalse
.renumerateIRIElements
- Optional Boolean indicating if SVG IRI addressable elements should be renumerated. Defaults totrue
.
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'), {
afterAll(elementsLoaded) {
console.log(`injected ${elementsLoaded} elements`)
},
afterEach(err, svg) {
if (err) {
throw err
}
console.log(`injected ${svg.outerHTML}`)
},
beforeEach(svg) {
svg.setAttribute('stroke', 'red')
},
cacheRequests: false,
evalScripts: 'once',
httpRequestWithCredentials: false,
renumerateIRIElements: false,
})
Installation
⚠️This library uses
Array.from()
, so if you're targeting browsers that don't support that method, you'll need to ensure an appropriate polyfill is included manually. See this issue comment for further detail.
$ npm install @tanem/svg-injector
There are also UMD builds available via unpkg:
- https://unpkg.com/@tanem/svg-injector/dist/svg-injector.umd.development.js
- https://unpkg.com/@tanem/svg-injector/dist/svg-injector.umd.production.js
Credit
This is a fork of a library originally developed by Waybury for use in iconic.js, part of the Iconic icon system.
License
MIT