Grunt task for converting a set of images into a spritesheet and corresponding CSS variables.
A folder of icons processed by grunt-spritesmith
:
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;
...
grunt-spritesmith
is supported and tested on Windows, Linux, and Mac OSX.
Support us via gittip or spread word on Twitter
grunt-spritesmith
can be installed via npm: npm install grunt-spritesmith
If you would like to use an engine with external dependencies, verify you have satisfied its 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
grunt.initConfig({
sprite:{
all: {
src: 'path/to/your/sprites/*.png',
destImg: '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 "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-spritesmith
is a grunt multitask. It is configured on a per-task basis using the following template:
grunt.initConfig({
'sprite': {
'all': {
// Sprite files to read in
'src': ['public/images/sprites/*.png'],
// Location to output spritesheet
'destImg': 'public/images/sprite.png',
// Stylus with variables under sprite names
'destCSS': 'public/css/sprite_positions.styl',
// OPTIONAL: Manual override for imgPath specified in CSS
'imgPath': '../sprite.png',
// 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, pngsmith)
'engine': 'canvas',
// OPTIONAL: Specify CSS format (inferred from destCSS' extension by default)
// (stylus, scss, scss_maps, sass, less, json, json_array, css)
'cssFormat': 'json',
// OPTIONAL: Specify a function or Mustache template to use for rendering destCSS
// Mutually exclusive to cssFormat
// More information can be found below
'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.name = 'sprite-' + sprite.name;
},
// OPTIONAL: Specify settings for algorithm
'algorithmOpts': {
// Skip sorting of images for algorithm (useful for sprite animations)
'sort': false
},
// OPTIONAL: Specify settings for engine
'engineOpts': {
'imagemagick': true
},
// OPTIONAL: Specify img options
'imgOpts': {
// Format of the image (inferred from destImg' extension by default) (jpg, png)
'format': 'png',
// gm only: Quality of image
'quality': 90,
// phantomjs only: Milliseconds to wait before terminating PhantomJS script
'timeout': 10000
},
// 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-' + item.name;
}
}
}
}
});
top-down (default) | 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.
The cssTemplate
option allows for specification of a custom templating function or Mustache
template to render your CSS.
If you pass in a Function
, it should have a signature of function (params) {}
and return a String
.
If you pass in a String
, we treat this as a path; reading in the file and rendering it via mustache.js. The template will be passed the same params
as in the Function
case.
An example template is https://github.com/twolfson/json2css/blob/4.2.0/lib/templates/stylus.template.mustache
params
is an object with some normalization nicities from json2css
, our default collection of templates.
- params
Object
- 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 encodedimage
- source_image
String
- Path to the original sprite file - offset_x
Number
- Negative value ofx
. Useful tobackground-position
- offset_y
Number
- Negative value ofy
. Useful tobackground-position
- px
Object
- Container for numeric values includingpx
- x
String
-x
suffixed withpx
- y
String
-y
suffixed withpx
- width
String
-width
suffixed withpx
- height
String
-height
suffixed withpx
- total_width
String
-total_width
suffixed withpx
- total_height
String
-total_height
suffixed withpx
- offset_x
String
-offset_x
suffixed withpx
- offset_y
String
-offset_y
suffixed withpx
- x
- name
- options
Object
- Options passed in viacssOpts
ingrunt-spritesmith
config
- items
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"
}
}
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 pngsmith
engine uses pngparse
, an JavaScript png
parser, to interpret images into ndarrays
. This requires no additional steps before installation.
Key differences: It requires no additional installation steps but you are limited to .png
files for your source files.
The phantomjs
engine relies on having phantomjs installed on your machine. Visit the phantomjs website for installation instructions.
Key differences: phantomjs
is the easiest engine to install that supports all image formats.
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
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
.
Image Magick is implicitly discovered. However, you can explicitly use it via engineOpts
{
'engineOpts': {
'imagemagick': true
}
}
If npm
exits normally, everything should work. These errors are being caused by npm
attempting to install the various spritesmith
engines.
If you have specified an engine
in your config, then you must satisfy its requirements before installing grunt-spritesmith
.
To remedy this, verify you have installed the appropriate set of requirements for your engine:
https://github.com/Ensighten/grunt-spritesmith#requirements
Afterwards, re-install grunt-spritesmith
so it detects the satisfied requirements for your engine.
npm install grunt-spritesmith
If you are running grunt-spritesmith
before 1.21.0
, then you have not satisfied any of the requirements for any of the engines before installing grunt-spritesmith
. If you are running 1.21.0
or greater, then there is a bug and please open a new issue.
The current version of
grunt-spritesmith
can be determined vianpm ls grunt-spritesmith
.
To remedy the issue before 1.21.0
, choose an engine and verify you have installed the appropriate set of requirements:
https://github.com/Ensighten/grunt-spritesmith#requirements
Afterwards, re-install grunt-spritesmith
so it detects the satisfied requirements for your engine.
npm install grunt-spritesmith
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 are maintained via Ensighten/spritesmith. If you would like to add one, please submit it via a pull request.
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.
Copyright (c) 2012-2014 Ensighten
Licensed under the MIT license.