grunt-spritesheet

@2x your spritesheets.

npm install grunt-spritesheet
4 downloads in the last day
30 downloads in the last week
114 downloads in the last month

grunt-spritesheet

Generate a CSS sprite sheet out of individual PNGs with support for multiple sprites per CSS file. Any png with an @2x suffix is dropped into an alternate retina display sprite and handled accordingly in the CSS template.

Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-spritesheet --save-dev

One the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-spritesheet');

The "spritesheet" task

Overview

In your project's Gruntfile, add a section named spritesheet to the data object passed into grunt.initConfig().

grunt.initConfig({
  spritesheet: {
    generate: {

      // An array of filename / source images array pairs. The basename of the sprite file
      // is also prefixed to the CSS classes.
      sprites: {
        "filename.png": ['/images/**/*.png'],
        ...
      },

      // The destination for the build stylesheet
      sheet: "stylesheet.css",

      // A mustache template used to render your sprites in a css file. (Optional)
      templateUrl: "path/to/template.mustache",

      // Optionally pass additional options to spritesmith
      spritesmithOptions: {

      }
    }
  }
})

Mustache Templates

Templates are parsed using mustache. If no template url is given, the default template is rendered.

Templates are given two lists: std and dbl representing standard and pixel doubled (retina) graphics. Each item contains:

  • sprite Spritesheet url

  • spriteWidth Width of the spritesheet as a whole

  • spriteHeight Height of the spritesheet as a whole

  • name Name of the sprite

  • width Width of the sprite

  • height Height of the sprite

  • x X coordinates of the sprite in the spritesheet

  • y Y coordinates of the sprite in the spritesheet

{{#std}}
.{{&name}} {
  background-image: url({{&sprite}});
  width: {{width}}px;
  height: {{height}}px;
  background-position: -{{x}}px -{{y}}px;
}
{{/std}}

@media
only screen and (-webkit-min-device-pixel-ratio: 2),
only screen and (   -moz-min-device-pixel-ratio: 2),
only screen and (   min--moz-device-pixel-ratio: 2),
only screen and (   -ms-min-device-pixel-ratio: 2),
only screen and (     -o-min-device-pixel-ratio: 2/1),
only screen and (        min-device-pixel-ratio: 2),
only screen and (                min-resolution: 192dpi),
only screen and (                min-resolution: 2dppx) { 
  {{#dbl}}
  .{{&name}} {
    background-image: url({{&sprite}});
    width: {{width}}px;
    height: {{height}}px;
    background-position: -{{x}}px -{{y}}px;
    background-size: {{spriteWidth}}px {{spriteHeight}}px;
  }
  {{/dbl}}
}

Contributing

A few ideas for future development:

  • General code cleanup.
  • Unit tests.
  • Big time CSS optimization.
  • Base64 sprite embedding in stylesheet
  • Custom prefixes rather than using filenames.
  • Option to build output CSS with grunt-contrib-cssmin.
npm loves you