Skip to content
Go to file
Cannot retrieve contributors at this time
executable file 247 lines (174 sloc) 8.16 KB

svg-sprite NPM version Build Status Coverage Status Dependency Status Development Dependency Status

This file is part of the documentation of svg-sprite — a free low-level Node.js module that takes a bunch of SVG files, optimizes them and creates SVG sprites of several types. The package is hosted on GitHub.

Tweaking and adding output formats

Sprite & shape variables

For each sprite generation process, a data object is constructed that is passed to the Mustache templating engine for rendering the different resources. You can access these templating values via the data argument passed to the compile() callback. Example:

    // Data object for the `mymode` output key
    mymode: {
        // Name of the current output mode
        mode: 'css',
        // Key used for result files & data
        key: 'mymode',
        // Indicator whether a `common` CSS class name has been specified
        hasCommon: false,
        // Given CSS class name for `common` sprite shape properties (NULL if disabled)
        common: null,
        // Effective `common` CSS class / mixin name (identical to `common`, defaulting to 'svg-common' if disabled)
        commonName: 'svg-common',
        // Indicator whether a `mixin` name has been specified
        hasMixin: false,
        // Mixin name for common sprite shape properties (NULL if disabled)
        mixinName: null,
        // Whether to create shape dimensioning CSS rules 
        includeDimensions: true,
        // Padding added to each shape (pixel)
        padding: {top: 30, right: 30, bottom: 30, left: 30},
        // Overall sprite width (pixel)
        spriteWidth: 860,
        // Overall sprite height (pixel)
        spriteHeight: 1020,
        // Relative path from the stylesheet resource to the SVG sprite
        sprite: 'svg/sprite.css.svg',
        // Relative path from the example resource to the SVG sprite (if configured)
        example: 'svg/sprite.css.svg'
        // List of all shapes in the sprite
        shapes: [
            // Single shape properties
                // Shape name (possibly including state, e.g. "weather-clear-night~hover")
                name: 'weather-clear-night',
                // Shape name excluding the state
                base: 'weather-clear-night',
                // Shape width (pixel)
                width: {  
                    // Excluding padding
                    inner: 800,
                    // Including padding
                    outer: 860
                // Shape height (pixel)
                height: {
                    // Excluding padding
                    inner: 960,
                    // Including padding
                    outer: 1020
                // First shape in the sprite
                first: true,
                // Last shape in the sprite
                last: false,
                // Shape position within the sprite
                position: {  
                    // Absolute position (pixel)
                    absolute: {
                        // Horizontal position  
                        x: 0,
                        // Horizontal position
                        y: -120,
                        // Compound position
                        xy: '0 -120px'
                    // Relative position (%)
                    relative: { 
                        // Horizontal position  
                        x: 0,
                        // Vertical position
                        y: 33.333333,
                        // Compound position
                        xy: '0 33.333333%'
                // CSS selectors
                selector: {
                    // Shape positioning CSS rule
                    shape: [  
                            expression: '.svg-weather-clear-night',
                            raw: '.svg-weather-clear-night',
                            first: true, // First selector expression
                            last: false
                            expression: '.svg-weather-clear-night\\:regular',
                            raw: '.svg-weather-clear-night:regular', // Unescaped version
                            first: false,
                            last: true // Last selector expression
                    // Shape dimensioning CSS rule
                    dimensions: [  
                            expression: '.svg-weather-clear-night-dims',
                            raw: '.svg-weather-clear-night-dims',
                            first: true, // First selector expression
                            last: true // Last selector expression
                // Dimensioning rule strategy
                dimensions: {  
                    // Render dimensions as part of positioning rule
                    inline: false,
                    // Render dimensions as separate dimensioning rule
                    extra: true
                // Shape SVG (inline embeddable version)
                svg: '<svg> ... </svg>',
        // Current date (RFC-1123)
        date: 'Fri, 26 Dec 2014 12:06:55 GMT',

Builtin templating functions

There are a couple of functions directly built into svg-sprite. You may use them in any template.


Takes no arguments and returns the current date and time as GMT string (e.g. Mon, 22 Dec 2014 16:18:53 GMT).

<p>Generated at {{date}} by svg-sprite</p>


Returns the negative value of a floating point number.

.offset-background {
    background-position: {{#invert}}{{positionX}}{{/invert}}px {{#invert}}{{positionY}}{{/invert}}px;


Returns the innermost part of a CSS selector as a class name (with the leading dot stripped off). For instance, if fullselector had the value .svg .icon-cart,

<i class="{{#classname}}{{fullselector}}{{/classname}}">Cart</i>

would become

<i class="icon-cart">Cart</i>


Finds all backslashes in a string and escapes each of them with another backslash.

{{#escape}}{{selector-with-backslash}}{{/escape}} {
    color: red;


Finds all hash signs in a string and encodes each of them to %23.

.{{name}}-background {
  background: url('data:image/svg+xml;utf-8,{{#encodeHashSign}}{{{svg}}}{{/encodeHashSign}}') no-repeat;
You can’t perform that action at this time.