svg-sprite

SVG sprites & stacks galore — A low-level Node.js module that takes a bunch of SVG files, optimizes them and bakes them into SVG sprites of several types along with suitable stylesheet resources (e.g. CSS, Sass, LESS, Stylus, etc.)

svg-sprite

is a low-level Node.js module that takes a bunch of SVG files, optimizes them and bakes them into SVG sprites of several types:

  • Traditional CSS sprites for use as background images,
  • CSS sprites with pre-defined <view> elements, useful for foreground images as well,
  • inline sprites using the <defs> element,
  • inline sprites using the <symbol> element
  • and SVG stacks.

It comes with a set of Mustache templates for creating stylesheets in good ol' CSS or one of the major pre-processor formats (Sass, Less and Stylus). Tweaking the templates or even adding your own custom output format is really easy, just as switching on the generation of an HTML example document along with your sprite.

Being a low-level library with support for Node.js streams, svg-sprite doesn't take on the part of accessing the file system (i.e. reading the source SVGs from and writing the sprites and CSS files to disk). If you don't want to take care of this stuff yourself, you might rather have a look at the available wrappers for Grunt (grunt-svg-sprite) and Gulp (gulp-svg-sprite). svg-sprite is also the foundation of the iconizr project, which serves high-quality SVG based CSS icon kits with PNG fallbacks.

To install svg-sprite globally, run

npm install svg-sprite -g

on the command line.

Crafting a sprite with svg-sprite typically follows these steps:

  1. You create an instance of the SVGSpriter, passing a main configuration object to the constructor.
  2. You register a couple of SVG source files for processing.
  3. You trigger the compilation process and receive the generated files (sprite, CSS, example documents etc.).

The procedure is the very same for all supported sprite types («modes»).

// Create spriter instance (see below for `config` examples) 
var spriter       = new SVGSpriter(config);
 
// Add SVG source files — the manual way ... 
spriter.add('assets/svg-1.svg', null, fs.readFileSync('assets/svg-1.svg', {encoding: 'utf-8'}));
spriter.add('assets/svg-2.svg', null, fs.readFileSync('assets/svg-2.svg', {encoding: 'utf-8'}));
    /* ... */
 
// Compile the sprite 
spriter.compile(function(errorresult) {
    /* ... Write `result` files to disk or do whatever with them ... */
});

As you can see, big parts of the above are dealing with disk I/O. In this regard you can make your life easier by using the Grunt or Gulp wrappers instead of the standard API.

Of course you noticed the config variable passed to the constructor in the above example. This is svg-sprite's main configuration — an Object with the following properties:

{
    dest            : <String>,             // Main output directory 
    log             : <String|Logger>,      // Logging verbosity or custom logger 
    shape           : <Object>,             // SVG shape configuration 
    transform       : <Array>,              // SVG transformations 
    svg             : <Object>,             // Common SVG options 
    variables       : <Object>,             // Custom templating variables 
    mode            : <Object>              // Output mode configurations 
}

If you don't provide a configuration object altogether, svg-sprite uses built-in defaults for these properties, so in fact they are all optional. However, you will need to enable at least one output mode (mode property) to get reasonable results (i.e. a sprite of some type).

Many configuration properties (all except mode) apply to all sprites created by the same spriter instance. The default values are:

// Common svg-sprite config options and their default values 
 
var config                  = {
    dest                    : '.',                      // Main output directory 
    log                     : null,                     // Logging verbosity (default: no logging) 
    shape                   : {                         // SVG shape related options 
        id                  : {                         // SVG shape ID related options 
            separator       : '--',                     // Separator for directory name traversal 
            generator       : function() { /*...*/ },   // SVG shape ID generator callback 
            pseudo          : '~'                       // File name separator for shape states (e.g. ':hover') 
        },
        dimension           : {                         // Dimension related options 
            maxWidth        : 2000,                     // Max. shape width 
            maxHeight       : 2000,                     // Max. shape height 
            precision       : 2,                        // Floating point precision 
            attributes      : false,                    // Width and height attributes on embedded shapes 
        },
        spacing             : {                         // Spacing related options 
            padding         : 0,                        // Padding around all shapes 
            box             : 'content'                 // Padding strategy (similar to CSS `box-sizing`) 
        },
        meta                : null,                     // Path to YAML file with meta / accessibility data 
        align               : null,                     // Path to YAML file with extended alignment data 
        dest                : null                      // Output directory for optimized intermediate SVG shapes 
    },
    transform               : ['svgo'],                 // List of transformations / optimizations 
    svg                     : {                         // General options for created SVG files 
        xmlDeclaration      : true,                     // Add XML declaration to SVG sprite 
        doctypeDeclaration  : true,                     // Add DOCTYPE declaration to SVG sprite 
        namespaceIDs        : true,                     // Add namespace token to all IDs in SVG shapes 
        dimensionAttributes : true                      // Width and height attributes on the sprite 
    },
    variables               : {}                        // Custom Mustache templating variables and functions 
}

Please refer to the configuration documentation for details.

At the moment, svg-sprite supports five different output modes (i.e. sprite types), each of them having it's own characteristics and use cases. It's up to you to decide which sprite type is the best choice for your project. The mode option controls which sprite types are created. You may enable more than one output mode at a time — svg-sprite will happily create several sprites in parallel.

To enable the creation of a specific sprite type with default values, simply set the appropriate mode property to true:

var config                  = {
    mode                    :
        css                 : true,     // Create a «css» sprite 
        view                : true,     // Create a «view» sprite 
        defs                : true,     // Create a «defs» sprite 
        symbol              : true,     // Create a «symbol» sprite 
        stack               : true      // Create a «stack» sprite 
    }
}

To further configure a sprite, pass in an object with configuration options:

// «symbol» sprite with CSS stylesheet resource 
 
var config                  = {
    mode                    :
        css                 : {
            // Configuration for the «css» sprite 
            // ... 
        }
    }
}

Many mode properties are shared between the different sprite types, but there are also type specific options. Please refer to the configuration documentation for a complete list of settings.

// Common mode properties 
 
var config                  = {
    mode                    :
        <mode>              : {
            dest            : "<mode>",                     // Mode specific output directory 
            prefix          : "svg-%s",                     // Prefix for CSS selectors 
            dimensions      : "-dims",                      // Suffix for dimension CSS selectors 
            sprite          : "svg/sprite.<mode>.svg"       // Sprite path and name 
            bust            : true|false,                   // Cache busting (mode dependent default value) 
            render          : {                             // Stylesheet rendering definitions 
                /* -------------------------------------------
                css         : false,                        // CSS stylesheet options
                scss        : false,                        // Sass stylesheet options
                less        : false,                        // LESS stylesheet options
                styl        : false                         // Stylus stylesheet options
                <custom>    : ...                           // Custom stylesheet options
                ------------------------------------------- */
            },
            example         : false                         // Create an HTML example document 
        }
    }
}

Foreground image sprite with <symbol> elements (for being <use>d in your HTML source):

// «symbol» sprite with CSS stylesheet resource 
 
var config                  = {
    mode                    :
        inline              : true,     // Prepare for inline embedding 
        symbol              : true      // Create a «symbol» sprite 
    }
}

Traditional CSS sprite with a Sass stylesheet:

// «css» sprite with Sass stylesheet resource 
 
var config                  = {
    mode                    :
        css                 : {         // Create a «css» sprite 
            render          : {
                scss        : true      // Render a Sass stylesheet 
            }
        }
    }
}

<defs> sprite, <symbol> sprite and an SVG stack all at once:

// «defs», «symbol» and «stack» sprites in parallel 
 
var config                  = {
    mode                    :
        defs                : true,
        symbol              : true,
        stack               : true
    }
}

mode-less run, returning the optimized SVG shapes only:

// Just optimize source SVG files, create no sprite 
 
var config                  = {
    shape                   :
        dest                : 'path/to/out/dir'
    }
}

NOTE ABOUT THE dest OPTION(S)

"Didn't you say that svg-sprite doesn't access the file system? So why do you need an output directory?" — Well, good point. svg-sprite uses vinyl file objects to pass along virtual resources and to specify where they are intended to be located. This is especially important for relative file paths (e.g. the path of an SVG sprite as used by a CSS stylesheet).

To get you quickly off the ground, I made a simple online configurator that lets you create a custom svg-sprite configuration in seconds. You may download the results as plain JSON, Node.js project, Gruntfile or Gulpfile. Please visit the configurator at http://jkphl.github.io/svg-sprite.

In order to improve accessibility, svg-sprite can read meta data from a YAML file and inject <title> and <description> elements into your SVGs. Please refer to the meta data injection guide for details.

For CSS sprites using a "horizontal" or "vertical" layout it is sometimes desirable to align the shapes within the sprite. With the help of an external YAML file, svg-sprite can not only control the alignment for each individual shape but also create displaced copies of them without significantly increasing the sprite's file size.

svg-sprite uses Mustache templates for rendering the various CSS resources. This makes it very easy to tailor the generated CSS / Sass / LESS / Stylus resources to your needs or add completely new output formats. Please refer to the templating guide to learn about the details.

svg-sprite comes with a pretty feature complete command line version. A typical example could look like this:

$ svg-sprite --css --css-render-css --css-example --dest=out assets/*.svg

Please refer to the CLI guide for further details.

  • SVGO does not minify element IDs when there are <style> or <script> elements contained in the file

Please refer to the changelog for a complete release history.

Copyright © 2015 Joschi Kuphal joschi@kuphal.net / @jkphl. svg-sprite is licensed under the terms of the MIT license. The contained example SVG icons are part of the Tango Icon Library and belong to the Public Domain.