Convert a set of images into a spritesheet and CSS variables via gulp
This is the official port of grunt-spritesmith, the grunt equivalent of a wrapper around spritesmith.
Alternative output formats include SASS, Stylus, LESS, and JSON.
Support us via gittip or spread word on Twitter
Install the module with: npm install gulp.spritesmith
var gulp = require('gulp');
var spritesmith = require('gulp.spritesmith');
gulp.task('sprite', function () {
var spriteData = gulp.src('images/*.png').pipe(spritesmith({
imgName: 'sprite.png',
cssName: 'sprite.css'
}));
spriteData.pipe(gulp.dest('path/to/output/'));
});
In addition to the spriteData
stream, we offer individual streams for images and CSS. This allows for image optimization and CSS minification.
var gulp = require('gulp');
var csso = require('gulp-csso');
var imagemin = require('gulp-imagemin');
var spritesmith = require('gulp.spritesmith');
gulp.task('sprite', function () {
// Generate our spritesheet
var spriteData = gulp.src('images/*.png').pipe(spritesmith({
imgName: 'sprite.png',
cssName: 'sprite.css'
}));
// Pipe image stream through image optimizer and onto disk
spriteData.img
.pipe(imagemin())
.pipe(gulp.dest('path/to/image/folder/'));
// Pipe CSS stream through CSS optimizer and onto disk
spriteData.css
.pipe(csso())
.pipe(gulp.dest('path/to/css/folder/'));
});
gulp.spritesmith
presents the spritesmith
function as its module.exports
.
gulp plugin that returns a transform stream with 2 readable stream properties.
The input/output streams interact with vinyl-fs objects which are gulp's format of choice.
- params
Object
- Container forgulp.spritesmith
parameters- imgName
String
- Filename to save image as- Supported image extensions are
.png
and.jpg/jpeg
(limited to specfic engines) - Image format can be overridden via
imgOpts.format
- Supported image extensions are
- cssName
String
- Filename to save CSS as - imgPath
String
- Optional path to use in CSS referring to image location - engine
String
- Optional image generating engine to use- By default,
auto
will be used which detects the best supported engine for your system - Supported options are
phantomjs
,canvas
,gm
, andpngsmith
- More information can be found in the engine section
- By default,
- algorithm
String
- Optional method for how to pack images- Supported options are
top-down
(default),left-right
,diagonal
,alt-diagonal
, andbinary-tree
- More information can be found in the algorithm section
- Supported options are
- padding
Number
- Optional amount of pixels to include between images- By default, there will be no padding
- imgOpts
Object
- Options for image output- format
String
- Override for format of output image- Supported values are
png
andjpg
(limited to specific engines)
- Supported values are
- quality
Number
- Quality of image (only supported bygm
engine) - timeout
Number
- Milliseconds to wait before terminating render (limited tophantomjs
engine)
- format
- algorithmOpts
Object
- Options for algorithm configuration- sort
Boolean
- Enable/disable image sorting byalgorithm
- By default, sorting is enabled (
true
)
- By default, sorting is enabled (
- sort
- engineOpts
Object
- Options for engine configuration- imagemagick
Boolean
- Force usage ofimagemagick
overgraphicsmagick
(limited togm
)
- imagemagick
- cssFormat
String
- Override for format of CSS output - cssVarMap
Function
- Iterator to customize CSS variable names- An example can be found here
- cssTemplate
Function|String
- CSS templating function or path to alternative mustache template- More information can be found in the cssTemplate section
- cssOpts
Object
- Container for CSS templates- functions
Boolean
- Skip output of mixins - cssClass
Function
- Iterator to override default CSS selectors- An example can be found here
- functions
- imgName
Returns:
- spriteData
stream.Transform
- Stream that outputs image and CSS as vinyl-fs objects - spriteData.img
stream.Readable
- Stream for image output as a vinyl-fs object - spriteData.css
stream.Readable
- Stream for CSS output as a vinyl-fs object
For cross-platform accessibility, spritesmith offers multiple sprite engines. Each of these engines has a different set of 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.
spritesmith has been tested against [email protected]
.
Key differences: phantomjs
is the easiest engine to install that supports all image formats.
The canvas
engine uses node-canvas which has a dependency on Cairo. Installation instructions can be found in the node-canvas wiki.
Additionally, you will need to install node-gyp for the C++ bindings.
npm install -g node-gyp
Key differences: canvas
has the best performance (useful for over 100 sprites). However, it is limited to UNIX
.
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 [email protected]
.
Key differences: gm
has the most options for export via imgOpts
.
spritesmith
offers a variety of image patterns via twolfson/layout.
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.
gulp.spritespritesmith
allows you to define your own CSS template, either via a function
or mustache template.
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"
}
}
Task configuration:
gulp.task('sprite', function () {
var spriteData = gulp.src('images/*.png').pipe(spritesmith({
imgName: 'sprite.png',
cssName: 'sprite.styl',
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;
}
}));
spriteData.img.pipe(gulp.dest('path/to/image/folder/'));
spriteData.css.pipe(gulp.dest('path/to/styl/folder/'));
});
CSS output:
/* As opposed to `$fork_x = 0px;` */
$sprite-fork_x = 0px;
$sprite-fork_y = 0px;
$sprite-fork_offset_x = 0px;
$sprite-fork_offset_y = 0px;
...
Task configuration:
gulp.task('sprite', function () {
var spriteData = gulp.src('images/*.png').pipe(spritesmith({
imgName: 'sprite.png',
cssName: 'sprite.css',
cssOpts: {
cssClass: function (item) {
// `item` has `x`, `y`, `width`, `height`, `name`, `image`, and more
// It is suggested to `console.log` output
return '.sprite-' + item.name;
}
}
}));
spriteData.img.pipe(gulp.dest('path/to/image/folder/'));
spriteData.css.pipe(gulp.dest('path/to/css/folder/'));
});
CSS output:
/* As opposed to .fork { */
.sprite-fork {
background-image: url(sprite.png);
background-position: 0px 0px;
width: 32px;
height: 32px;
}
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 gulp.spritesmith
.
To remedy this, verify you have installed the appropriate set of requirements for your engine:
https://github.com/twolfson/gulp.spritesmith#engines
Afterwards, re-install gulp.spritesmith
so it detects the satisfied requirements for your engine.
npm install gulp.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 gulp
and test via npm test
.
GitHub and Twitter icons were taken from Alex Peattie's JustVector Social Icons.
Fork designed by P.J. Onori from The Noun Project.
As of Feb 09 2014, Todd Wolfson has released this repository and its contents to the public domain.
It has been released under the UNLICENSE.