README

svgSprite.js

Why?

Using SVG can be tricky, so many ways to use SVG, styling limitations, CORS issues, bad browsers support, etc. svgSprite is a selection of the best hacks and techniques available.
Handle inserted elements at any time, mandatory for SPA and website injecting content in pages.
Easiest way to migrate from webfont to SVG icons set, replacing any icon systems with SVG sprite without markup change.

How?

By using a simple data-svg attribute in your markup:

<i data-svg="icon-a"></i>…
<i data-svg="icon-z"></i>…

and a terse js API:

svgSprite({source: 'https://example.com/assets/icons.svg'})

You'll get the SVG sprite injected in DOM and single SVGs pointing to SVG sprite symbols:

<i data-svg="icon-a"><svg role="presentation"><use xlink:href="#icon-a"/></svg></i>…
<i data-svg="icon-z"><svg role="presentation"><use xlink:href="#icon-z"/></svg></i>…
<svg dispay="none" data-source="https://example.com/assets/icons.svg">
  <symbol id="icon-a">…</symbol>…
  <symbol id="icon-z">…</symbol>…
</svg>

Alternativelly, you can inline SVGs (using an external sprite) already in DOM:

<svg><use xlink:href="https://example.com/assets/graphics.svg#logo"/></svg>…
<svg><use xlink:href="https://example.com/assets/graphics.svg#worldmap"/></svg>…

By simply calling:

svgSprite.inline()

Again, you'll get single SVGs pointing to symbol in a unique inlined SVG sprite:

<svg><use xlink:href="#logo"/></svg>…
<svg><use xlink:href="#worldmap"/></svg>…
<svg dispay="none" data-source="https://example.com/assets/graphics.svg">
  <symbol id="logo">…</symbol>…
  <symbol id="worldmap">…</symbol>…
</svg>

Features

Watch inserted nodes (looking for data-svg / SVG with external ressource), then inject or swap SVGs pointing to inlined sprite very efficiently (use events, no polling).
Targets specifc 'elements' using a simple selector or a node list.
Use as many SVG sprites as you want.
Cache and deduplicate requests of external SVG sprites sources.
Accepts URL and SVG markup sources, caching may be done with network and/or local storage.
Use semantic and accessibility attributes to hide sprites and decorate injected / swapped SVGs.
May be used at any time even before DOM is loaded.
Allows advanced customization with a simple callback:
- Specify 'viewbox' attribute to size and pad SVG symbols.
- Keep short meaningful names in data-svg attribute with prefixed/suffixed ids in SVG sprite.
- Rename / alias some elements in an symbol or icon set.
- Use custom markup even without data-svg attribute.
Zero dependencies.
Only 1.6Kb minified & gzipped.
UMD loader with named AMD definition included.

Browser support

Targets evergreen browsers only, but successfully tested (some demo animation may not work thought) via Browserling & BrowserStack with Chrome 21+, Firefox 16+, IE 10+, Opera 16+, Safari 7.1, Safari iOS 9 & Android 4.4.

Examples

Ugly demo with helpful commented sources.

Installation

NPM

npm i

Quick & dirty CDN

<script src="https://cdn.rawgit.com/adriengibrat/svgSprite/v1.2.0/svgSprite.min.js"></script>

Old school

Download the svgSprite.min.js file and add it to your project.

API

svgSprite()

svgSprite({
    source: url || markup
    , elements: selector || collection // optional
    , before: function (svg, id, use, element, sprite, source) { // optional
        // 'svg' is the SVG element before it is injected
        // 'id' is the id used by default as fragment in xlink:href attribute (e.g. data-svg value)
        // 'use' is a utility function to optionaly change the SVG use tag xlink:href attribute
        // 'element' is the element where the SVG will be injected
        // 'sprite' is the SVG sprite already injected in DOM
        // 'source' is the source (URL or markup) of the SVG sprite

        // return false to avoid injecting the SVG in the element
    }
})
// returns a function (see below)

svgSprite.inline()

svgSprite.inline({
    elements: selector || collection // optional
    , before: function (svg, id, sprite, source) { // optional
        // 'svg' is the SVG element pointing to external resource
        // 'id' is the id used as fragment in xlink:href attribute
        // 'sprite' is the SVG sprite already injected in DOM
        // 'source' is the source URL of the SVG sprite

        // return false to avoid changing the SVG use tag xlink:href attribute
    }
})
// returns a function (see below)

returned callback

The function returned by svgSprite() and svgSprite.inline() always returns the list of SVGs already processed.

N.B.: all process are async, the lists may contain null values:

when the SVG is not injected yet (sprite load is pending).
when the SVG or its use tag have been removed from DOM.
when the SVG injection has been prevented (before() returning false).

const done = svgSprite({ source: 'https://example.com/sprite.svg' }) // or svgSprite.inline()
…
// prevents new elements to be proccessed
done(true)
    // and remove all injected SVGs
    .forEach(svg => svg && svg.remove())

When 'elements' is not a collection, calling the function returned with a truthy argument also pevents the new elements injected from being processed.

Dev

Install via npm

npm install

Start bundling watch

npm start

Check bundle size

npm run size

Roadmap

The demo needs a graphic designer, help wanted ;)
Create a simple tool to generate SVG sprite with symbols & views that allow SVG external link, inlining, fragment identifiers to use as img src / css background, nice previews, clean source, with easy symbol discovery and visualisation.

License

You may use this software under the WTF Public License.

Author

Adrien Gibrat – https://github.com/adriengibrat

Credits

Thanks to:

Jonathan Neal's svg4everybody insprired me and was great source of useful information.
Iconic SVGInjector for the cache & inject external SVG then swap elements lead.
Sara Soueidan's great articles about SVG, very detailed and inspiring.
Daniel Buchner's post & David Walsh's article for, respectively, inventing & spreading great hacks.
Iconic Icons, Material icons, Evil icons, Fontastic icons & Octicons used in the demo via Jsdelivr & Rawgit.

SVG sprite best practices

Define viewBox

You should use symbol tags and always define custom viewboxes:

<symbol id="asset-id" viewBox="left top width height">
    <path …/> …
</symbol>

Accessibility

You may add usefull descriptive tags and aria attributes.

<defs role="presentation">
    <symbol id="asset-id" viewBox="left top width height" aria-labelledby="title">
        <title>Meaningful name</title>
        <path …/> …
    </symbol>
    <symbol id="another-id" viewBox="left top width height" aria-labelledby="title desc">
        <title>Another name</title>
        <desc>Longer description</desc>
        <path …/> …
    </symbol>
    …
</defs>

SVG attributes

When inlined in HTML5 xmlns attributes are useless, but you should keep them on your sprite SVGs if they are consumed by another way (via css by example).

<svg xmlns="http://www.w3.org/2000/svg"[ xmlns:xlink="http://www.w3.org/1999/xlink"]>
    …
</svg>

Optimize SVG

Use the great SVGO cli:

Install

npm i -g svgo

Basic usage

svgo sprite.svg

Create SVG sprite

Thanks to svg-sprite, it's quite simple:

Install

npm i -g svg-sprite

Basic usage

svg-sprite --symbol --symbol-dest=. --symbol-sprite=sprite.svg svg/*.svg

Usage no npm install needed!

README

svgSprite.js

Why?

How?

Features

Browser support

Examples

Installation

NPM

Quick & dirty CDN

Old school

API

svgSprite()

svgSprite.inline()

returned callback

Dev

Install via npm

Start bundling watch

Check bundle size

Roadmap

License

Author

Credits

SVG sprite best practices

Define viewBox

Accessibility

SVG attributes

Optimize SVG

Install

Basic usage

Create SVG sprite

Install

Basic usage