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.
grunt-spritesmith
can be installed via npm: npm install grunt-spritesmith
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
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)
'engine': 'canvas',
// OPTIONAL: Specify CSS format (inferred from destCSS' extension by default)
// (stylus, scss, sass, less, json, jsonArray, css)
'cssFormat': 'json',
// 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',
// 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-' + 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.
Support this project and others by twolfson via gittip.
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.
For cross-platform accessibility, spritesmith has and supports multiple sprite engines. However, each of these current engines has a different set of external dependencies.
The phantomjs
engine relies on having phantomjs installed on your machine. Visit the phantomjs website for installation instructions.
spritesmith has been tested against [email protected]
.
The canvas
engine uses node-canvas which has a dependency on Cairo.
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.
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
}
}
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-2013 Ensighten
Licensed under the MIT license.