Naboo's Podracing Misadventure
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    grunt-spritely Build status

    A Grunt 0.4 or newer task for converting a set of images into a spritesheet and corresponding CSS variables.

    This package is forked from grunt-spritesmith and makes the following changes:

    • uses the Grunt 0.4 standard this.options and this.files instead of raw This is adventageous for using this task together with grunt-newer.
    • adds the options mapSrcToName and mapDestImageToUrl. mapDestImageToUrl replaces the imgPath option.

    A folder of icons processed by grunt-spritely:

    Fork icon + GitHub icon + Twitter icon =

    generates a 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;

    Cross-platform support

    grunt-spritely is supported and tested on Windows, Linux, and Mac OSX.

    Getting Started

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

    Before proceeding, verify you have satisfied your preferred engine's requirements.

    Then, add and configure it to your grunt file (grunt.js or Gruntfile.js depending on your version):

    module.exports = function (grunt) {
      // Configure grunt 
        spritely: {
          all: {
            src: 'path/to/your/sprites/*.png',
            destImg: 'destination/of/spritesheet.png',
            destCSS: 'destination/of/sprites.css'
      // Load in `grunt-spritely` 

    Run the grunt sprite task:

    $ grunt sprite
    Running "sprite:all" (sprite) task
    Files "spritesheet.png", "sprites.styl" created.
    Done, without errors.

    Results are a spritesheet and CSS:


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


    grunt-spritely is a grunt multitask. It is configured on a per-task basis using the following template:

      spritely: {
        all: {
          // Sprite files to read in 
          src: ['public/images/sprites/*.png'],
          // Location of the image to output 
          dest: 'public/images/sprite.png',
          options: {
            // Stylus with variables under sprite names 
            destCSS: 'public/css/sprite_positions.styl',
            // OPTIONAL: Transform the input image file name to the identifier used for the sprite. 
            mapSrcToName: 2,
            // OPTIONAL: Transform the output image file into a URL 
            mapDestImageToUrl: 2,
            // OPTIONAL: Specify algorithm (top-down, left-right, diagonal [\ format], 
                // alt-diagonal [/ format], binary-tree [best packing]) 
            // Visual representations can be found below 
            algorithm: 'alt-diagonal',
            // OPTIONAL: Specify padding between images 
            padding: 2,
            // OPTIONAL: Specify engine (auto, phantomjs, canvas, gm) 
            engine: 'canvas',
            // OPTIONAL: Specify CSS format (inferred from destCSS extension by default) 
                // (stylus, scss, sass, less, json, jsonArray, css) 
            cssFormat: 'json',
            // OPTIONAL: Specify a Mustache template to use for destCSS; mutually exclusive to cssFormat 
            cssTemplate: 'public/css/sprite_positions.styl.mustache',
            // OPTIONAL: Map variable of each sprite 
            cssVarMap: function (sprite) {
              // `sprite` has `name`, `image` (full path), `x`, `y` 
              //   `width`, `height`, `total_width`, `total_height` 
              // EXAMPLE: Prefix all sprite names with 'sprite-' 
     = 'sprite-' +;
            // OPTIONAL: Specify settings for engine 
            engineOpts: {
              imagemagick: true
            // OPTIONAL: Specify img options 
            imgOpts: {
               // Format of the image (inferred from destImg's extension by default) (jpg, png) 
               format: 'png',
               // Quality of image (gm only) 
               quality: 90
            // OPTIONAL: Specify css options 
            cssOpts: {
              // Some templates allow for skipping of function declarations 
              functions: false,
              // CSS template allows for overriding of CSS selectors 
              cssClass: function (item) {
                return '.sprite-' +;

    Specifying files

    Files may be specified using several different grunt-standard formats described here: For example: ## New configuration examples #### One sheet

    spritely: {
      all: {
        options: {
          destCSS: 'destination/of/sprites.css'
        src: 'path/to/your/sprites/*.png',
        dest: 'destination/of/spritesheet.png'

    Multiple sheets

    spritely: {
      all: {
        options: {
          destCSS: 'destination/of/sprites.css'
        files: [
            src: 'path/to/your/sprites/core/*@1x.png',
            dest: 'destination/of/core@1x.png',
            src: 'path/to/your/sprites/core/*@2.png',
            dest: 'destination/of/core@2x.png',
            src: 'path/to/your/sprites/detail-page/*@1x.png',
            dest: 'destination/of/detail-page@1x.png',
            src: 'path/to/your/sprites/detail-page/*@2x.png',
            dest: 'destination/of/detail-page@2x.png',


    top-down (default) left-right diagonal alt-diagonal binary-tree
    top-down left-right diagonal alt-diagonal binary-tree

    For best packing, use binary-tree which uses a solution to the rectangle packing problem.

    If you are worried about sprites being visible within other sprites, use alt-diagonal.

    If you are using a repeating background, top-down or left-right depending on your occasion.

    The diagonal algorithm exists for you if you need it.


    For cross-platform accessibility, spritesmith has and supports multiple sprite engines. However, each of these current engines has a different set of external dependencies.

    If you are running into issues, consult the FAQ section.


    The phantomjs engine relies on having phantomjs installed on your machine. Visit the phantomjs website for installation instructions.

    Key differences: phantomjs is the most accessible engine.

    spritesmith has been tested against phantomjs@1.9.0.


    The canvas engine uses node-canvas which has a dependency on Cairo.

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

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

    Additionally, you will need to install node-gyp for the C++ bindings.

    sudo npm install -g node-gyp

    gm (Graphics Magick / Image Magick)

    The gm engine depends on Graphics Magick or Image Magick.

    Key differences: gm has the most options for export via imgOpts.

    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.

    spritesmith has been developed and tested against 1.3.17.

    If you are using Image Magick, you must specify it in engineOpts

      'engineOpts': {
        'imagemagick': true


    I am seeing errors during installation.

    If npm exits normally, everything should work. These errors are being caused by npm attempting to install the various spritesmith engines.


    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 grunt and test via npm test.


    Algorithms are maintained via twolfson/layout. If you would like to add one, please submit it via a pull request.

    Engines and image options

    Engines and image options are maintained via Ensighten/spritesmith. If you would like to add one, please submit it via a pull request.

    CSS formats

    CSS formats are maintained via twolfson/json2css. If you would like to add one, please submit it via a pull request.


    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.


    Support this project and others by twolfson via gittip.

    Support via Gittip


    Copyright (c) 2012-2013 Ensighten

    Licensed under the MIT license.




    npm i grunt-spritely

    Downloadslast 7 days







    last publish


    • avatar