Home

Awesome

grunt-spritesmith Build status Subscribe to newsletter

Grunt task for converting a set of images into a spritesheet and corresponding CSS variables.

A folder of icons processed by grunt-spritesmith:

Fork icon + GitHub icon + Twitter icon =

generates a spritesheet:

Spritesheet

and CSS variables (available in CSS, JSON, SASS, SCSS, LESS, Stylus):

$fork_offset_x = 0px;
$fork_offset_y = 0px;
$fork_width = 32px;
$fork_height = 32px;
...
$github_offset_x = -32px;
$github_offset_y = 0px;
$github_width = 32px;
$github_height = 32px;
...

Retina support

As of grunt-spritesmith@4.5.0, retina spritesheets/templates are supported. See the Retina parameters section for more information.

Cross-platform support

grunt-spritesmith is supported and tested on Windows, Linux, and Mac OS X.

Do you like grunt-spritesmith?

Support us via donations or spread word on Twitter

Breaking changes in 5.0.0

We are normalizing sprite variables even further to convert any non-alphanumeric/non-dash/non-underscore character to a delimiter character (e.g. -). This allows us to support naming retina sprites with @2x suffixes, to prevent regressions like #137.

Breaking changes in 6.0.0

We have moved from spritesmith-engine-spec@1.1.0 to spritesmith-engine-spec@2.0.0. This means if you use an custom engine (e.g. gmsmith, canvassmith), then you will need to upgrade it.

npm install my-engine-smith@latest --save-dev

This is to enable usage of streaming outputs from engines.

Getting Started

grunt-spritesmith can be installed via npm: npm install grunt-spritesmith

Then, add and configure it to your Gruntfile.js:

module.exports = function (grunt) {
  // Configure grunt
  grunt.initConfig({
    sprite:{
      all: {
        src: 'path/to/your/sprites/*.png',
        dest: 'destination/of/spritesheet.png',
        destCss: 'destination/of/sprites.css'
      }
    }
  });

  // Load in `grunt-spritesmith`
  grunt.loadNpmTasks('grunt-spritesmith');
};

Run the grunt sprite task:

$ grunt sprite
Running "sprite:all" (sprite) task
Files "destination/of/spritesheet.png", "destination/of/sprites.css" created.

Done, without errors.

Results are a spritesheet:

Spritesheet

and CSS:

.icon-fork {
  background-image: url(spritesheet.png);
  background-position: 0px 0px;
  width: 32px;
  height: 32px;
}
...

Documentation

grunt-spritesmith is a grunt multitask. It supports the following parameters:

Retina parameters

grunt-spritesmith supports retina spritesheet generation via retinaSrcFilter and retinaDest. If at least one of these is provided, then we will expect the other and enable retina spritesheet generation.

Repeated parameters have the same properties as above but are repeated for clarity with respect to retina spritesheets.

An example retina spritesheet setup can be found in the Examples section.

Algorithms

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-downleft-rightdiagonalalt-diagonalbinary-tree
top-downleft-rightdiagonalalt-diagonalbinary-tree

More information can be found in the layout documentation:

https://github.com/twolfson/layout

Templating

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

https://github.com/twolfson/spritesheet-templates/blob/9.3.1/lib/templates/stylus.template.handlebars

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

An example sprite 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"
  }
}

If you are defining a Handlebars template, then you can inherit from an existing template via handlebars-layouts (e.g. {{#extend "scss"}}). An example usage can be found in the Examples section.

Example usages can be found as:

Variable mapping

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 sprites 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;

Engines

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:

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

This repository adheres to specification version: 2.0.0

Below is a list of known engines with their tradeoffs:

pixelsmith

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

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

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.

[node-canvas wiki]: (https://github.com/LearnBoost/node-canvas/wiki/_pages [node-gyp]: https://github.com/TooTallNate/node-gyp/

gmsmith

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.

Examples

Algorithm

In this example, we will use the alt-diagonal algorithm to layout sprites in a non-intersecting manner.

Configuration:

{
  src: ['fork.png', 'github.png', 'twitter.png'],
  dest: 'spritesheet.algorithm.png',
  destCss: 'spritesheet.algorithm.styl',
  algorithm: 'alt-diagonal'
}

Output:

algorithm spritesheet

Engine

In this example, we will use the gmsmith engine to support obscure image formats.

Requirements:

Install gmsmith to our node_modules via npm install.

npm install gmsmith

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

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

Configuration:

{
  src: ['fork.png', 'github.png', 'twitter.png'],
  dest: 'spritesheet.algorithm.png',
  destCss: 'spritesheet.algorithm.styl',
  engine: 'gmsmith'
}

Output:

engine spritesheet

Padding

The padding option allows for inserting spacing between images.

Configuration:

{
  src: ['fork.png', 'github.png', 'twitter.png'],
  dest: 'spritesheet.padding.png',
  destCss: 'spritesheet.padding.styl',
  padding: 20 // Exaggerated for visibility, normal usage is 1 or 2
}

Output:

padding spritesheet

Retina spritesheet

In this example, we will use generate a normal and retina spritesheet via the retinaSrcFilter and retinaDest parameters.

Configuration:

{
  // We have `fork.png`, `fork@2x.png`, ...
  src: ['fork*.png', 'github*.png', 'twitter*.png'],
  // This will filter out `fork@2x.png`, `github@2x.png`, ... for our retina spritesheet
  //   The normal spritesheet will now receive `fork.png`, `github.png`, ...
  retinaSrcFilter: ['*@2x.png'],
  dest: 'spritesheet.retina.png',
  retinaDest: 'spritesheet.retina@2x.png',
  destCss: 'spritesheet.retina.styl'
}

Normal spritesheet:

Normal spritesheet

Retina spritesheet:

Retina spritesheet

Handlebars template

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

Template:

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

Configuration:

{
  src: ['fork.png', 'github.png', 'twitter.png'],
  dest: 'spritesheet.handlebarsStr.png',
  destCss: 'spritesheet.handlebarsStr.css',
  cssTemplate: 'handlebarsStr.css.handlebars'
}

Output:

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

Handlebars inheritance

In this example, we will extend the SCSS template to provide minimal variables. The JSON at the front comes from the original template and is required to provide consistent casing and default options.

Different block sections for each template are documented in:

https://github.com/twolfson/spritesheet-templates

Template:

{
  // Default options
  'functions': true,
  'variableNameTransforms': ['dasherize']
}

{{#extend "scss"}}
{{#content "sprites"}}
{{#each sprites}}
${{strings.name}}: ({{px.x}}, {{px.y}}, {{px.offset_x}}, {{px.offset_y}}, {{px.width}}, {{px.height}}, {{px.total_width}}, {{px.total_height}}, '{{{escaped_image}}}', '{{name}}', );
{{/each}}
{{/content}}
{{#content "spritesheet"}}
${{spritesheet_info.strings.name_sprites}}: ({{#each sprites}}${{strings.name}}, {{/each}});
${{spritesheet_info.strings.name}}: ({{spritesheet.px.width}}, {{spritesheet.px.height}}, '{{{spritesheet.escaped_image}}}', ${{spritesheet_info.strings.name_sprites}}, );
{{/content}}
{{/extend}}

Configuration:

{
  src: ['fork.png', 'github.png', 'twitter.png'],
  dest: 'spritesheet.handlebarsInheritance.png',
  destCss: 'spritesheet.handlebarsInheritance.css',
  cssTemplate: 'handlebarsInheritance.scss.handlebars'
}

Output:

$fork: (0px, 0px, 0px, 0px, 32px, 32px, 64px, 64px, 'spritesheet.handlebarsInheritance.png', 'fork', );
$github: (32px, 0px, -32px, 0px, 32px, 32px, 64px, 64px, 'spritesheet.handlebarsInheritance.png', 'github', );
$twitter: (0px, 32px, 0px, -32px, 32px, 32px, 64px, 64px, 'spritesheet.handlebarsInheritance.png', 'twitter', );
$spritesheet-sprites: ($fork, $github, $twitter, );
$spritesheet: (64px, 64px, 'spritesheet.handlebarsInheritance.png', $spritesheet-sprites, );
/* ... */

Template function

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

Configuration:

// var yaml = require('js-yaml');
{
  src: ['fork.png', 'github.png', 'twitter.png'],
  dest: 'spritesheet.yamlTemplate.png',
  destCss: 'spritesheet.yamlTemplate.yml',
  cssTemplate: function (data) {
    // Convert sprites from an array into an object
    var spriteObj = {};
    data.sprites.forEach(function (sprite) {
      // Grab the name and store the sprite under it
      var name = sprite.name;
      spriteObj[name] = sprite;

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

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

Output:

fork:
  x: 0
  "y": 0
  width: 32
  height: 32
  source_image: fork.png
  image: spritesheet.yamlTemplate.png
  total_width: 64
  total_height: 64
  escaped_image: spritesheet.yamlTemplate.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:
  x: 32
  # ...

Contributing

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.

Attribution

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

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

Plus and Equals icons were built using the Ubuntu Light typeface.

License

Copyright (c) 2012 Todd Wolfson

Licensed under the MIT license.