images go in, sprites come out


spritestream reads from a stream of retina and non-retina image files and spits out sprite sheets and an accompanying CSS file. It is designed for use with Gulp.

Pipe your source files into spritestream, and provide a callback. The callback will receive either an error or an array of results with the non-retina sprite image, the retina sprite image, and the CSS file, in that order.

spritestream assumes that for each image.png, there is an accompanying image@2x.png for use in the retina sprite sheet.

var es           = require('event-stream');
var gulp         = require('gulp');
var spritestream = require('spritestream');
gulp.src('./images/**/*.png').pipe(spritestream(function(errresults) {
  if (err) { throw err; }

Use a custom CSS class. By default, classes will be named like .icon and .icon-image-name. These can be changed to .sprite and .sprite-image-name, for example, by passing sprite.

Set to true to append an md5 hash of the file contents to the end of its name.

The path, relative to the ultimate pipe destination, to attach to the image Vinyl file objects.

The path, relative to the ultimate pipe destination, to attach to the CSS Vinyl file objects.

Provide a template to use other than the default one. This will be compiled with EJS. See the existing template in templates/sprites.css.ejs for an example. Can be a string or a Buffer.

This example will result in the following files:

  • ./public/images/sprites-34509438543098abcde.png
  • ./public/images/sprites-234098234098234908a@2x.png
  • ./public/stylesheets/sprites-styles-2340823049823094098.css
  cssClass  : 'sprite',
  digest    : true,
  imagesPath: './images/sprites',
  cssPath   : './stylesheets/sprites-styles'
}, function(errresults) {
npm install spritestream --save

Automated tests:

npm test

Manual tests:

npm run test-server

The icons used in the test suite—"Watch", "Breakfast", "Sketchbook", and "Twinkie"—were designed by Edward Boatman from thenounproject.com.