TypeScript icon, indicating that this package has built-in type declarations

3.1.2 • Public • Published

External SVG Polyfill npm CDN

Small and basic polyfill to support referencing external SVG files

Browser like IE9-IE11, Edge12, Safari 5.1-6, or UCWeb11 do not support referencing external files via location hash. Referencing external files can be especially useful when dealing with a technique called SVG sprites, where multiple SVG elements are stored within a single SVG file. It is possible to inline these SVG sprites into the HTML document itself, but this has several disadvantages i.e. caching issues, unneeded HTML file size growth, development inconveniences, etc. Externally referenced SVG sprites mitigate those problems but are not supported in the mentioned browsers.

external-svg-polyfill embeds referenced SVG files automatically.


  • User-agent sniffing is used to determine feature support.
  • External SVG files are fetched via xhr and embedded while use elements are updated.
  • Cross-domain SVG files are fetched and embedded for all browsers to work around browser limitations.
  • To prevent naming collision issues, id attributes are updated to use a unique name.
  • Dynamically added SVG use elements are processed upon changes in the DOM.
  • Various lifecycle events get dispatched on relevant DOM elements.
  • Minified file size is below 5 KiB to keep the load, parse and execution times low.
  • Script is not self-executing, it needs to be called explicitly.
  • Project is written in TypeScript.




npm install @thasmo/external-svg-polyfill


<script src="https://cdn.jsdelivr.net/npm/@thasmo/external-svg-polyfill@3/browser/bundle.min.js"></script>


Just define some svg use elements in the HTML markup and let external-svg-polyfill do the rest.

Static Website

<!doctype html>
        <script src="https://cdn.jsdelivr.net/npm/@thasmo/external-svg-polyfill@2/browser/bundle.min.js"></script>
            window.document.addEventListener('DOMContentLoaded', function() {
                new ExternalSvgPolyfill();
        <svg xmlns="http://www.w3.org/2000/svg">
            <use href="/static/sprite.svg#icon"></use>

Web Application

import ExternalSvgPolyfill from '@thasmo/external-svg-polyfill';
new ExternalSvgPolyfill();


method description
run Run the polyfill manually if the run option is set to false.
observe Start observing the DOM for changes if the observe option is set to false.
unobserve Stop observing the DOM for changes.
destroy Stop the polyfill, stop observing and restore the original markup.
detect Run browser detection manually if the detect option is set to false.


option description type default
target SVG use elements to process. string, SVGUseElement[], NodeListOf<SVGUseElement> svg use
context Element within to search for SVG use elements. HTMLElement window.document.body ?: window.document.documentElement
root Element to which prepend SVG embeds to. HTMLElement window.document.body ?: window.document.documentElement
run Run the polyfill on object instantiation. boolean true
prefix Prefix id attribute values to ensure uniqueness. false won't change the attributes. boolean true
detect Detect browser-support automatically. false will run the polyfill in any browser. boolean true
observe Observe DOM changes within the context element and rerun the polyfill. boolean true
crossdomain Embed crossdomain SVG files for all browsers regardless. boolean true
namespace Namespace of the dispatched events. string external-svg-polyfill
agents Array of regular expressions matching relevant user agents to polyfill. RegExp[] [/Edge\/12/, /Version\/6\.0.+Safari/, /UCBrowser\/11/]


All event are prefixed with the namespace option, are bubbling and can be cancelled using event.preventDefault().

event description data
external-svg-polyfill.load An external SVG file is loaded via xhr. address
external-svg-polyfill.insert An external SVG file is inserted. address, file
external-svg-polyfill.remove An external SVG file is removed. address
external-svg-polyfill.apply An SVG use element's href attribute is updated. address, identifier
external-svg-polyfill.revoke An SVG use element's href attribute is restored. value


external-svg-polyfill can polyfill these browsers:

  • Internet Explorer 11 tested
  • UCWeb 11 untested


Some alternatives exist and, in fact, external-svg-polyfill was greatly inspired by them. Check them out!



BrowserStack loves open source and provides free manual and automated testing for this project! ❤️


MIT license

FOSSA Status


Package Sidebar


npm i @thasmo/external-svg-polyfill

Weekly Downloads






Unpacked Size

61 kB

Total Files


Last publish


  • thasmo