Convert a set of images into a spritesheet and CSS variables via gulp

This is the official port of grunt-spritesmith, the grunt equivalent of a wrapper around spritesmith.

Alternative output formats include SASS, Stylus, LESS, and JSON.

Support us via gratipay or spread word on Twitter

We have moved to pixelsmith as the default engine. It is node based and should support your sprites. Any other engines must be installed outside of spritesmith. This will lead to cleaner and faster installations.

We have moved to binary-tree as the default algorithm. We changed this to give the best possible packing out of the box. If you were using top-down as the default, please specify it in your configuration.

We have moved the cssClass option for the css template to cssSelector. This makes it more semantically appropriate and eaiser to find.

Install the module with: npm install gulp.spritesmith

var gulp = require('gulp');
var spritesmith = require('gulp.spritesmith');

gulp.task('sprite', function () {
  var spriteData = gulp.src('images/*.png').pipe(spritesmith({
    imgName: 'sprite.png',
    cssName: 'sprite.css'
  }));
  spriteData.pipe(gulp.dest('path/to/output/'));
});

In addition to the spriteData stream, we offer individual streams for images and CSS. This allows for image optimization and CSS minification.

var gulp = require('gulp');
var csso = require('gulp-csso');
var imagemin = require('gulp-imagemin');
var spritesmith = require('gulp.spritesmith');

gulp.task('sprite', function () {
  // Generate our spritesheet
  var spriteData = gulp.src('images/*.png').pipe(spritesmith({
    imgName: 'sprite.png',
    cssName: 'sprite.css'
  }));

  // Pipe image stream through image optimizer and onto disk
  spriteData.img
    .pipe(imagemin())
    .pipe(gulp.dest('path/to/image/folder/'));

  // Pipe CSS stream through CSS optimizer and onto disk
  spriteData.css
    .pipe(csso())
    .pipe(gulp.dest('path/to/css/folder/'));
});

gulp.spritesmith presents the spritesmith function as its module.exports.

gulp plugin that returns a transform stream with 2 readable stream properties.

The input/output streams interact with vinyl-fs objects which are gulp's format of choice.

• params Object - Container for gulp.spritesmith parameters
  • imgName String - Filename to save image as
    • Supported image extensions are .png and .jpg/jpeg (limited to specfic engines)
    • Image format can be overridden via imgOpts.format
  • cssName String - Filename to save CSS as
    • Supported CSS extensions are .css (CSS), .sass (SASS), .scss (SCSS), .less (LESS), .styl/.stylus (Stylus), and .json (JSON)
    • CSS format can be overridden via cssFormat
  • imgPath String - Optional path to use in CSS referring to image location
  • padding Number - Optional amount of pixels to include between images
    • By default we use no padding between images (0)
    • An example usage can be found in the Examples section
  • algorithm String - Optional method for how to pack images
    • By default we use binary-tree, which packs images as efficiently as possible
    • An example usage can be found in the Examples section
    • More information can be found in the Algorithms section
  • algorithmOpts Object - Options to pass through to algorithm
    • For example we can skip sorting in some algorithms via {algorithmOpts: {sort: false}}
      • This is useful for sprite animations
    • See your algorithm's documentation for available options
      • https://github.com/twolfson/layout#algorithms
  • engine String - Optional image generating engine to use
    • By default we use pixelsmith, a node based engine that supports all common image formats
    • Alternative engines must be installed via npm install
    • An example usage can be found in the Examples section
    • More information can be found in the Engines section
  • engineOpts Object - Options to pass through to engine for settings
    • For example phantomjssmith accepts timeout via {engineOpts: {timeout: 10000}}
    • See your engine's documentation for available options
  • imgOpts Object - Options to pass through to engine uring export
    • For example gmsmith supports quality via {exportOpts: {quality: 75}}
    • See your engine's documentation for available options
  • cssFormat String - CSS format to use
    • By default this is the format inferred by cssName's extension
      • For example .styl -> stylus
    • For more format options, see our formatting library
      • https://github.com/twolfson/spritesheet-templates#templates
  • cssTemplate String|Function - CSS template to use for rendering output CSS
    • This overrides cssFormat
    • If a String is provided, it must be a path to a mustache template
      • An example usage can be found in the Examples section
    • If a Function is provided, it must have a signature of function (params)
      • An example usage can be found in the Examples section
    • For more templating information, see the Templating section
  • cssVarMap Function - Mapping function for each filename to CSS variable
    • For more information, see Variable mapping
  • cssSpritesheetName String - Name to use for spritesheet related variables in preprocessor templates
  • cssOpts Object - Options to pass through to templater
    • For example {cssOpts: {functions: false}} skips output of mixins
    • See your template's documentation for available options
      • https://github.com/twolfson/spritesheet-templates#templates

Returns:

• spriteData stream.Transform - Stream that outputs image and CSS as vinyl-fs objects
• spriteData.img stream.Readable - Stream for image output as a vinyl-fs object
• spriteData.css stream.Readable - Stream for CSS output as a vinyl-fs object

Images can be laid out in different fashions depending on the algorithm. We use layout to provide you as many options as possible. At the time of writing, here are your options for algorithm:

top-down	left-right	diagonal	alt-diagonal	binary-tree

More information can be found in the layout documentation:

https://github.com/twolfson/layout

The cssTemplate option allows for using a custom template. An example template can be found at:

https://github.com/twolfson/spritesheet-templates/blob/4.2.0/lib/templates/stylus.template.mustache

The parameters passed into your template are known as params. We add some normalized properties via spritesheet-templates for your convenience.

• params Object Container for parameters
  • items Object[] - Array of sprite information
    • name String - Name of the sprite file (sans extension)
    • x Number - Horizontal position of sprite's left edge in spritesheet
    • y Number - Vertical position of sprite's top edge in spritesheet
    • width Number - Width of sprite
    • height Number - Height of sprite
    • total_width Number - Width of entire spritesheet
    • total_height Number - Height of entire spritesheet
    • image String - Relative URL path from CSS to spritesheet
    • escaped_image String - URL encoded image
    • source_image String - Path to the original sprite file
    • offset_x Number - Negative value of x. Useful to background-position
    • offset_y Number - Negative value of y. Useful to background-position
    • px Object - Container for numeric values including px
      • x String - x suffixed with px
      • y String - y suffixed with px
      • width String - width suffixed with px
      • height String - height suffixed with px
      • total_width String - total_width suffixed with px
      • total_height String - total_height suffixed with px
      • offset_x String - offset_x suffixed with px
      • offset_y String - offset_y suffixed with px
  • spritesheet Object - Information about spritesheet
    • width Number - Width of entire spritesheet
    • total_height Number - Height of entire spritesheet
    • image String - Relative URL path from CSS to spritesheet
    • escaped_image String - URL encoded image
    • px Object - Container for numeric values including px
      • width String - width suffixed with px
      • height String - height suffixed with px
  • spritesheet_name String - Prefix for spritesheet variables
  • options Object - Options passed in via cssOpts in grunt-spritesmith config

An example sprite item is

{
  "name": "sprite2",
  "x": 10,
  "y": 20,
  "width": 20,
  "height": 30,
  "total_width": 80,
  "total_height": 100,
  "image": "nested/dir/spritesheet.png",
  "escaped_image": "nested/dir/spritesheet.png",
  "source_image": "path/to/original/sprite.png",
  "offset_x": -10,
  "offset_y": -20,
  "px": {
    "x": "10px",
    "y": "20px",
    "width": "20px",
    "height": "30px",
    "total_width": "80px",
    "total_height": "100px",
    "offset_x": "-10px",
    "offset_y": "-20px"
  }
}

Example usages can be found as:

• Mustache template
• Template function

The cssVarMap option allows customization of the CSS variable names

If you would like to customize CSS selectors in the css template, please see https://github.com/twolfson/spritesheet-templates#css

Your cssVarMap should be a function with the signature function (sprite). It will receive the same parameters as items from Templating except for escaped_image, offset_x, offset_y, and px.

// Prefix all sprite names with `sprite-` (e.g. `home` -> `sprite-home`)
cssVarMap: function (sprite) {
  sprite.name = 'sprite_' + sprite.name;
}

// Generates:
// $sprite_fork_x = 0px;
// $sprite_fork_y = 0px;

// As oppposed to default:
// $fork_x = 0px;
// $fork_y = 0px;

An engine can greatly improve the speed of your build (e.g. canvassmith) or support obscure image formats (e.g. gmsmith).

All spritesmith engines adhere to a common specification and test suite:

https://github.com/twolfson/spritesmith-engine-test

Below is a list of known engines with their tradeoffs:

pixelsmith is a node based engine that runs on top of get-pixels and save-pixels.

Key differences: Doesn't support uncommon image formats (e.g. tiff) and not as fast as a compiled library (e.g. canvassmith).

phantomjssmith is a phantomjs based engine. It was originally built to provide cross-platform compatibility but has since been succeeded by pixelsmith.

Requirements: phantomjs must be installed on your machine and on your PATH environment variable. Visit the phantomjs website for installation instructions.

Key differences: phantomjs is cross-platform and supports all image formats.

canvassmith is a node-canvas based engine that runs on top of Cairo.

Requirements: Cairo and node-gyp must be installed on your machine.

Instructions on how to install Cairo are provided in the node-canvas wiki.

node-gyp should be installed via npm:

npm install -g node-gyp

Key differences: canvas has the best performance (useful for over 100 sprites). However, it is UNIX only.

gmsmith is a gm based engine that runs on top of either Graphics Magick or Image Magick.

Requirements: Either Graphics Magick or Image Magick must be installed on your machine.

For the best results, install from the site rather than through a package manager (e.g. apt-get). This avoids potential transparency issues which have been reported.

Image Magick is implicitly discovered. However, you can explicitly use it via engineOpts

{
  engineOpts: {
    imagemagick: true
  }
}

Key differences: gmsmith allows for configuring image quality whereas others do not.

In this example, we are using the alt-diagonal algorithm to guarantee no overlap if images overflow.

Configuration:

{
  imgName: 'sprite.png',
  cssName: 'sprite.styl',
  algorithm: 'alt-diagonal'
}

Output:

In this example, we are using the phantomjssmith engine as an alternative to the pixelsmith default.

Requirements:

Install phantomjssmith to our node_modules via npm install.

npm install phantomjssmith

Alternatively, we can use --save or --save-dev to save to our package.json's dependencies or devDependenices.

npm install phantomjssmith --save  # Updates {"dependencies": {"phantomjssmith": "1.2.3"}}
npm install phantomjssmith --save-dev  # Updates {"devDependencies": {"phantomjssmith": "1.2.3"}}

Configuration:

// var phantomjssmith = require('phantomjssmith');
{
  imgName: 'sprite.png',
  cssName: 'sprite.styl',
  engine: phantomjssmith
}

Output:

The padding option allows for inserting spacing between images.

Configuration:

{
  imgName: 'sprite.png',
  cssName: 'sprite.styl',
  padding: 20 // Exaggerated for visibility, normal usage is 1 or 2
}

Output:

In this example, we will use cssTemplate with a mustache template to generate CSS that uses :before selectors.

Template:

{{#items}}
.icon-{{name}}:before {
  display: block;
  background-image: url({{{escaped_image}}});
  background-position: {{px.offset_x}} {{px.offset_y}};
  width: {{px.width}};
  height: {{px.height}};
}
{{/items}}

Configuration:

{
  imgName: 'sprite.png',
  cssName: 'sprite.css',
  cssTemplate: 'mustacheStr.css.mustache'
}

Output:

.icon-fork:before {
  display: block;
  background-image: url(sprite.png);
  background-position: 0px 0px;
  width: 32px;
  height: 32px;
}
.icon-github:before {
/* ... */

In this example, we will use cssTemplate with a custom function that generates YAML.

Configuration:

// var yaml = require('js-yaml');
{
  imgName: 'sprite.png',
  cssName: 'sprite.yml',
  cssTemplate: function (params) {
    // Convert items from an array into an object
    var itemObj = {};
    params.items.forEach(function (item) {
      // Grab the name and store the item under it
      var name = item.name;
      itemObj[name] = item;

      // Delete the name from the item
      delete item.name;
    });

    // Return stringified itemObj
    return yaml.safeDump(itemObj);
  }
}

Output:

fork:
  x: 0
  "y": 0
  width: 32
  height: 32
  source_image: /home/todd/github/gulp.spritesmith/docs/images/fork.png
  image: sprite.png
  total_width: 64
  total_height: 64
  escaped_image: sprite.png
  offset_x: -0.0
  offset_y: -0.0
  px:
    x: 0px
    "y": 0px
    offset_x: 0px
    offset_y: 0px
    height: 32px
    width: 32px
    total_height: 64px
    total_width: 64px
github:
# ...

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via npm run lint and test via npm test.

GitHub and Twitter icons were taken from Alex Peattie's JustVector Social Icons.

Fork designed by P.J. Onori from The Noun Project.

As of Feb 09 2014, Todd Wolfson has released this repository and its contents to the public domain.

It has been released under the UNLICENSE.