svg-sprite

What is svg-sprite?

The svg-sprite npm package is a powerful tool for creating SVG sprites. It allows you to combine multiple SVG files into a single file, which can then be used to optimize the delivery and performance of SVG assets in web applications. The package supports various modes of sprite generation, including symbol, stack, and CSS sprites, and provides a range of configuration options to customize the output.

What are svg-sprite's main functionalities?

Symbol Sprite Mode

This feature allows you to create a symbol sprite, which is a single SVG file containing multiple symbols. Each symbol can be referenced individually using the <use> element in your HTML.

const svgSprite = require('svg-sprite');
const config = {
  mode: {
    symbol: {
      dest: 'out',
      sprite: 'symbol-sprite.svg'
    }
  }
};
svgSprite(config).then(() => console.log('Symbol sprite created!'));

CSS Sprite Mode

This feature allows you to create a CSS sprite, which is a single SVG file that can be used with CSS to display individual icons. The package can also generate the corresponding CSS file to use the sprite.

const svgSprite = require('svg-sprite');
const config = {
  mode: {
    css: {
      dest: 'out',
      sprite: 'css-sprite.svg',
      render: {
        css: true
      }
    }
  }
};
svgSprite(config).then(() => console.log('CSS sprite created!'));

Stack Sprite Mode

This feature allows you to create a stack sprite, which is a single SVG file containing multiple stacked SVG elements. Each element can be referenced individually using the <use> element in your HTML.

const svgSprite = require('svg-sprite');
const config = {
  mode: {
    stack: {
      dest: 'out',
      sprite: 'stack-sprite.svg'
    }
  }
};
svgSprite(config).then(() => console.log('Stack sprite created!'));

Other packages similar to svg-sprite

svg-sprite-loader

svg-sprite-loader is a webpack loader that allows you to import SVG files as symbols in a sprite. It is similar to svg-sprite in that it helps optimize SVG delivery, but it is specifically designed to work with webpack, making it a good choice for projects that use webpack for module bundling.

gulp-svg-sprite

gulp-svg-sprite is a Gulp plugin for creating SVG sprites. It offers similar functionality to svg-sprite but is designed to be used within a Gulp build process. This makes it a good option for projects that use Gulp for task automation.

svgstore

svgstore is a simple tool for creating SVG sprites. It is less feature-rich compared to svg-sprite but provides a straightforward way to combine multiple SVG files into a single sprite. It is a good choice for projects that need a lightweight solution for SVG sprite generation.

README

svg-sprite

is a Node.js module that reads a folder of SVG images, optimizes them and creates an SVG sprite along with suitable CSS and / or Sass resources.

This is my first ever Node.js module, so please be forgiving in case of any errors (and please drop me a line in this case — I'd really appreciate that). At some point later, I'd like to provide a Node.js / Grunt / Gulp port of my PHP based iconizr project, which will use svg-sprite then. That said, you will find most of the configuration options to be identical with those of iconizr.

Installation & usage

To install svg-sprite, run

npm install svg-sprite -g

on the command line.

Command line usage

You may use svg-sprite as a command line tool. Type svg-sprite -h to get all the available options:

  Usage: svg-sprite [options] [command]

  Commands:

    *
  Convert the SVG files in the given directory. If omitted, the current working directory is used.

Options:

  -h, --help                           output usage information
  -V, --version                        output the version number
  -o, --out <css-directory>            Output directory for the CSS file and the sprite subdirectory
  --sassout <sass-directory>           Optional: separate output directory for Sass files [defaults to --out]
  -c, --css [css-filename]             Render CSS file (optionally provide a CSS file name, defaults to "sprite")
  -s, --sass [sass-filename]           Render Sass file (optionally provide a Sass file name, defaults to "sprite")
  --spritedir <sprite-directory>       Sprite subdirectory name [svg]
  --sprite <sprite-filename>           Sprite file name [sprite]
  -p, --prefix <selector-prefix>       CSS selector prefix [svg]
  --common <common-selector>           Common CSS selector for all images
  --maxwidth <max-width>               Maximum single image width [1000]
  --maxheight <max-height>             Maximum single image height [1000]
  --padding <padding>                  Transparent padding around the single images (in pixel)
  --pseudo <pseudo-separator>          Character sequence for denoting CSS pseudo classes [~]
  -d, --dims                           Render image dimensions as separate CSS and / or Sass rules
  -k, --keep                           Keep intermediate SVG files (inside the sprite subdirectory)
  -v, --verbose                        Output verbose progress information
  --cleanwith <clean-module>           Module to be used for SVG cleaning. Currently "scour" or "svgo" [scour]
  --cleanconfig <clean-configuration>  JSON-serialized configuration options for the cleaning module
  -q, --quiet                          Don't produce any output

To learn more about the options and their values please see below.

Examples

This command reads SVG files from the current directory and uses the subdirectory sprite to create an SVG sprite and CSS file into it:

$ svg-sprite --css --out sprite
$ svg-sprite -co sprite

This one creates an SVG sprite and a CSS file along with a Sass file at sprite/sass/_sprite.scss:

$ svg-sprite --css --out sprite --sass _sprite --sassout sprite/sass

This last one uses the subdirectory ./svg, creates image size CSS rules, optimizes the single SVG files using SVGO and doesn't discard them in the end:

$ svg-sprite --keep --dims --css --out sprite --cleanwith svgo ./svg
$ svg-sprite -kdco sprite --cleanwith svgo ./svg

Node.js module usage

The svg-sprite module exposes only one method, createSprite(). Use it like this:

var SVGSprite		= require('svg-sprite'),
var options			= {
	css				: true,
	sass			: '_sprite',
	sassout			: 'sass/output/directory'
	/* Further configuration options, see below ... */
},
callback			= function(err, results) { /*
	If no error occurs, `results` will be a JSON object like this one:
	
	{
	   success		: true,		// Overall success
	   length		: 3,		// Total number of files written
	   files		: {			// Files along with their file size in bytes
	      '/path/to/your/cwd/css/output/directory/svg/sprite.svg'	: 436823,
	      '/path/to/your/cwd/css/output/directory/sprite.css'		: 1821,
	      '/path/to/your/cwd/sass/output/directory/_sprite.scss'	: 2197
	   }
	}
	
*/};
SVGSprite.createSprite('path/with/svg/images', 'css/output/directory', options, callback);

The createSprite() method will refuse to run if you don't pass exactly four arguments:

1. A path to be used as the input directory containing the SVG files for creating the sprite. May be relative to the current working directory.
2. A general output directory, which is used to create the CSS file (if activated; see the css option below) and which serves as the parent directory for the sprite directory given by spritedir (see below). May be relative to the current working directory.
3. An object with configuration options. None of these options is mandatory, so you may pass an empty object {} here.
4. A callback to be run when the sprite creation has finished (with or without error).

Available options

These are the options you may pass as the createSprite() method's third argument:

Property	Type	Description
css	Boolean / String	If given and non-empty, a CSS file will be rendered, with the value being the file name (preceding the .css extension). If set to TRUE, the file name will be sprite.
sass	Boolean / String	If given and non-empty, a Sass file (SCSS) will be rendered, with the value being the file name (preceding the .scss extension). If set to TRUE, the file name will be sprite.
sassout	Directory path	Output directory for the Sass file (also see the sass option above, which needs to be set to create a Sass file). Defaults to the general output directory (second argument to createSprite()).
spritedir	Directory path	Directory relative to the general CSS output directory where the SVG sprite will be created. Defaults to svg.
sprite	String	Filename of the SVG sprite (preceding the .svg extension). Defaults to sprite.
prefix	String	Prefix for all CSS rules (CSS and Sass file). Defaults to svg (results in .svg-* CSS selectors)
common	String	If given and not empty, it will be used for creating a CSS selector that commonly defines the background-image and background-repeat properties for all the sprite images (thus saving some bytes by not unnecessarily repeating these properties for each image)
maxwidth	Integer	Maximum width of single SVG images. Will be downscaled if necessary. Defaults to 1000.
maxheight	Integer	Maximum height of single SVG images. Will be downscaled if necessary. Defaults to 1000.
padding	Integer	Padding around the single SVG images in the sprite. Defaults to 0.
pseudo	String	Char to determine the usage of CSS pseudo classes. See the iconizr documentation for details. Defaults to ~.
dims	-	If present, additional CSS rules will be rendered (both CSS and Sass) that set the dimensions of the single images. You can use these CSS rules for sizing your elements appropriately. In general, the suffix -dims will be used in conjunction with the regular CSS selector for the image, but please have a look at the generated CSS file as well as the iconizr documentation for some special rules regarding CSS pseudo classes.
keep	-	If present, the single optimized intermediate SVG images used for creating the sprite will not be discarded, but kept in the spritedir as well.
verbose	Integer	Set to a value > 0 to get some output. Defaults to 0.
cleanwith	String	Select the module used for optimizing the single SVG images. Currently, the Node.js modules svg-cleaner (loosely based on Scour) and SVGO are supported, so use either scour or svgo for this option. Set it to FALSE or NULL to skip the SVG optimization altogether. Defaults to scour (but this may change in the future).
cleanconfig	String (JSON)	You may provide a configuration object that is passed to the SVG optimizer (currently, only SVGO supports this). Provide it as a valid JSON string. Empty by default.

Known problems / To-do

• When several SVG images are combined into one file, the contained IDs should be namespaced to avoid conflicts between the images (e.g. when containing inline CSS). The namespacing of IDs is still to be implemented.
• There should be added some more tests, especially for comparing the created SVG sprite with the expected result. At the moment, however, there are some problems with the libraries that would have to be used ...

Release history

v0.0.5

• Fixed binary path in package.json (#1)

v0.0.4

• Changed devDependencies & added more tests

v0.0.3

• Fixed a bug with the Sass output

v0.0.2

• Fixed a bug that let the sprite creation fail when keeping the intermediate SVG files
• Added the common option
• Added some tests

v0.0.1

• Initial release

Legal

Copyright © 2014 Joschi Kuphal [e-mail] / @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.