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.
As of gulp.spritesmith@3.5.0
, retina spritesheets/templates are supported. See the Retina parameters section for more information.
Support us via donations or spread word on Twitter
We are normalizing sprite variables even further to convert any non-alphanumeric/non-dash/non-underscore character to a delimiter character (e.g. -
). This allows us to support naming retina sprites with @2x
suffixes, to prevent regressions like grunt-spritesmith#137.
We have moved from spritesmith-engine-spec@1.1.0 to spritesmith-engine-spec@2.0.0. This means if you use an custom engine (e.g. gmsmith
, canvassmith
), then you will need to upgrade it.
npm install my-engine-smith@latest --save-dev
This is enables us to use streaming outputs from engines in a future release.
Additionally, we have added support for buffer
and stream
content for in-memory engines (e.g. pixelsmith
, canvassmith
) which resolves #53.
We have completed our integration with streaming outputs from engines. As a result, Vinyl img
files will have stream
contents which were previously buffers.
If your img
pipeline requires Buffer
contents, then this can be remedied via vinyl-buffer:
// Throws error due to not supporting streams
spriteData.img.pipe(imagemin());
// Back to operational
var buffer = require('vinyl-buffer');
spriteData.img.pipe(buffer()).pipe(imagemin());
Gulp 5.0.0 introduced default encodings for src
and dest
streams of utf8
.
Since gulp.spritesmith
inputs and outputs images, we need to set {encoding: false}
for the image .src()
and .dest()
streams.
See "Getting Started" for an hands-on example.
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', {encoding: false}).pipe(spritesmith({
imgName: 'sprite.png',
cssName: 'sprite.css'
}));
return spriteData.pipe(gulp.dest('path/to/output/', {encoding: false}));
});
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 buffer = require('vinyl-buffer');
var csso = require('gulp-csso');
var imagemin = require('gulp-imagemin');
var merge = require('merge-stream');
var spritesmith = require('gulp.spritesmith');
gulp.task('sprite', function () {
// Generate our spritesheet
var spriteData = gulp.src('images/*.png', {encoding: false}).pipe(spritesmith({
imgName: 'sprite.png',
cssName: 'sprite.css'
}));
// Pipe image stream through image optimizer and onto disk
var imgStream = spriteData.img
// DEV: We must buffer our stream into a Buffer for `imagemin`
.pipe(buffer())
.pipe(imagemin())
.pipe(gulp.dest('path/to/image/folder/', {encoding: false}));
// Pipe CSS stream through CSS optimizer and onto disk
var cssStream = spriteData.css
.pipe(csso())
.pipe(gulp.dest('path/to/css/folder/'));
// Return a merged stream to handle both `end` events
return merge(imgStream, cssStream);
});
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 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 - padding
Number
- Optional amount of pixels to include between images- By default we use no padding between images (
0
) - An example usage can be found in the Examples section
- By default we use no padding between images (
- algorithm
String
- Optional method for how to pack images- By default we use
binary-tree
, which packs images as efficiently as possible - An example usage can be found in the Examples section
- More information can be found in the Algorithms section
- By default we use
- algorithmOpts
Object
- Options to pass through to algorithm- For example we can skip sorting in some algorithms via
{algorithmOpts: {sort: false}}
- This is useful for sprite animations
- See your algorithm's documentation for available options
- For example we can skip sorting in some algorithms via
- engine
String
- Optional image generating engine to use- By default we use
pixelsmith
, anode
based engine that supports all common image formats - Alternative engines must be installed via
npm install
- An example usage can be found in the Examples section
- More information can be found in the Engines section
- By default we use
- engineOpts
Object
- Options to pass through to engine for settings- For example
phantomjssmith
acceptstimeout
via{engineOpts: {timeout: 10000}}
- See your engine's documentation for available options
- For example
- imgOpts
Object
- Options to pass through to engine uring export- For example
gmsmith
supportsquality
via{imgOpts: {quality: 75}}
- See your engine's documentation for available options
- For example
- cssFormat
String
- CSS format to use- By default this is the format inferred by
cssName's
extension- For example
.styl -> stylus
- For example
- For more format options, see our formatting library
- By default this is the format inferred by
- cssTemplate
String|Function
- CSS template to use for rendering output CSS- This overrides
cssFormat
- If a
String
is provided, it must be a path to a handlebars template- An example usage can be found in the Examples section
- If a
Function
is provided, it must have a signature offunction (data)
- An example usage can be found in the Examples section
- For more templating information, see the Templating section
- This overrides
- cssHandlebarsHelpers
Object
- Container for helpers to register to handlebars for our template- Each key-value pair is the name of a handlebars helper corresponding to its function
- For example,
{half: function (num) { return num/2; }
will add a handlebars helper that halves numbers
- cssVarMap
Function
- Mapping function for each filename to CSS variable- For more information, see Variable mapping
- cssSpritesheetName
String
- Name to use for spritesheet related variables in preprocessor templates - cssOpts
Object
- Options to pass through to templater- For example
{cssOpts: {functions: false}}
skips output of mixins - See your template's documentation for available options
- For example
- imgName
Returns:
- spriteData
stream.Transform
- Stream that outputs image and CSS as Vinyl objects - spriteData.img
stream.Readable
- Stream for image output as a Vinyl objectcontents
will be aStream
- spriteData.css
stream.Readable
- Stream for CSS output as a Vinyl objectcontents
will be aBuffer
gulp.spritesmith
supports retina spritesheet generation via retinaSrcFilter
and retinaImgName
. If at least one of these is provided, then we will expect the other and enable retina spritesheet generation.
Repeated parameters have the same properties as above but are repeated for clarity with respect to retina spritesheets.
An example retina spritesheet setup can be found in the Examples section.
We receive both normal and retina sprites from the same gulp.src
so please include them in your original glob. (e.g. *.png
should include icon-home.png
and icon-home@2x.png
).
We strongly encourage using the @2x
suffix for retina sprites over -retina
or -2x
. There are known ordering issues caused when sharing a -
delimiter between sprite names and the retina suffix (see grunt-spritesmith#137).
- params
Object
- Container forgulp.spritesmith
parameters- retinaSrcFilter
String|String[]
- Filepaths to filter out from incoming stream for our retina spritesheet- This can be a glob as with
src
(e.g.sprite/*@2x.png
) - The path/glob used should line up with
gulp.src
(e.g.gulp.src('sprite/*.png', {encoding: false})
,retinaSrcFilter: 'sprite/*@2x.png'
) - For example
sprites/*@2x.png
will filter outsprite1@2x.png
for a separate retina spritesheet- Under the hood, we will group
sprite1.png
andsprite1@2x.png
as a group of normal/retina sprites
- Under the hood, we will group
- This can be a glob as with
- retinaImgName
String
- Filename to save retina spritesheet as - retinaImgPath
String
- Optional path to use in CSS referring to image location- For example
../sprite@2x.png
will yield CSS with:background-image: url(../sprite@2x.png);
- For example
- padding
Number
- Padding to place to right and bottom between sprites- By default there is no padding
- In retina spritesheets, this number will be doubled to maintain perspective
- cssFormat - CSS format to use
- By default this is the format inferred by
cssName's
extension- For example
.styl -> stylus_retina
- For example
- For more format options, see our formatting library
- By default this is the format inferred by
- cssVarMap
Function
- Mapping function for each filename to CSS variable- This will run through normal and retina spritesheets
- The name used for normal sprites dictates the group name for retina group variables (e.g.
$icon-home
will have group$icon-home-group
) - For more information, see Variable mapping
- cssRetinaSpritesheetName
String
- Name to use for retina spritesheet related variables in preprocessor templates - cssRetinaGroupsName
String
- Name to use for retina groups related variables in preprocessor templates
- retinaSrcFilter
Returns:
- spriteData
stream.Transform
- Stream that outputs image, retina image, and CSS as Vinyl objects - spriteData.img
stream.Readable
- Stream for image outputs (normal and retina) as a Vinyl objectcontents
will be aStream
- spriteData.css
stream.Readable
- Stream for retina CSS output as a Vinyl objectcontents
will be aBuffer
Images can be laid out in different fashions depending on the algorithm. We use layout
to provide you as many options as possible. At the time of writing, here are your options for algorithm
:
top-down |
left-right |
diagonal |
alt-diagonal |
binary-tree |
---|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
![]() |
More information can be found in the layout
documentation:
https://github.com/twolfson/layout
The cssTemplate
option allows for using a custom template. An example template can be found at:
The parameters passed into your template are known as data
. We add some normalized properties via spritesheet-templates
for your convenience.
- data
Object
Container for parameters- sprites
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
- spritesheet
Object
- Information about spritesheet- 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
- px
Object
- Container for numeric values includingpx
- width
String
-width
suffixed withpx
- height
String
-height
suffixed withpx
- width
- width
- spritesheet_info
Object
- Container forspritesheet
metadata and its representation- name
String
- Prefix for spritesheet variables
- name
- retina_sprites
Object[]
- Array of retina sprite information- This will only be accessible if we are generating a retina spritesheet
- Properties are the same as
sprites
(e.g.name
,width
,source_image
)
- retina_spritesheet
Object
- Information about retina spritesheet- This will only be accessible if we are generating a retina spritesheet
- Properties are the same as
spritesheet
(e.g.width
,px
)
- retina_spritesheet_info
Object
- Container forretina_spritesheet
metadata and its representation- This will only be accessible if we are generating a retina spritesheet
- name
String
- Prefix for spritesheet variables
- retina_groups
Object[]
- Array of objects that maps to normal and retina sprites- This will only be accessible if we are generating a retina spritesheet
-
Object
- Container for data about sprite mapping- name
String
- Name to refer to mapping by - index
Number
- Index of corresponding normal/retina sprites fromdata.sprites
/data.retina_sprites
- normal
Object
- Normal sprite fromdata.sprites
that corresponds to our mapping- This has all the same properties as
data.sprites[*]
(e.g.name
,x
,offset_y
,px
)
- This has all the same properties as
- retina
Object
- Retina sprite fromdata.retina_sprites
that corresponds to our mapping- This has all the same properties as
data.retina_sprites[*]
(e.g.name
,x
,offset_y
,px
)
- This has all the same properties as
- name
- retina_groups_info
Object
- Optional container for metadata aboutretina_groups
and its representation- This will only be accessible if we are generating a retina spritesheet
- name
String
- Name forretina_groups
- options
Object
- Options passed in viacssOpts
ingulp.spritesmith
config
- sprites
An example sprite
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"
}
}
If you are defining a Handlebars template, then you can inherit from an existing template via handlebars-layouts
(e.g. {{#extend "scss"}}
). An example usage can be found in the Examples section.
Example usages can be found as:
The cssVarMap
option allows customization of the CSS variable names
If you would like to customize CSS selectors in the
css
template, please see https://github.com/twolfson/spritesheet-templates#css
Your cssVarMap
should be a function with the signature function (sprite)
. It will receive the same parameters as sprites
from Templating except for escaped_image
, offset_x
, offset_y
, and px
.
// Prefix all sprite names with `sprite-` (e.g. `home` -> `sprite-home`)
cssVarMap: function (sprite) {
sprite.name = 'sprite_' + sprite.name;
}
// Generates:
// $sprite_fork_x = 0px;
// $sprite_fork_y = 0px;
// As oppposed to default:
// $fork_x = 0px;
// $fork_y = 0px;
An engine can greatly improve the speed of your build (e.g. canvassmith
) or support obscure image formats (e.g. gmsmith
).
All spritesmith
engines adhere to a common specification:
https://github.com/twolfson/spritesmith-engine-spec
This repository adheres to specification version: 2.0.0
Below is a list of known engines with their tradeoffs:
pixelsmith
is a node
based engine that runs on top of get-pixels
and save-pixels
.
Key differences: Doesn't support uncommon image formats (e.g. tiff
) and not as fast as a compiled library (e.g. canvassmith
).
phantomjssmith
is a phantomjs based engine. It was originally built to provide cross-platform compatibility but has since been succeeded by pixelsmith
.
Requirements: phantomjs must be installed on your machine and on your PATH
environment variable. Visit the phantomjs website for installation instructions.
Key differences: phantomjs
is cross-platform and supports all image formats.
canvassmith
is a node-canvas based engine that runs on top of Cairo.
Requirements: Cairo and node-gyp must be installed on your machine.
Instructions on how to install Cairo are provided in the node-canvas wiki.
node-gyp should be installed via npm
:
npm install -g node-gyp
Key differences: canvas
has the best performance (useful for over 100 sprites). However, it is UNIX
only.
gmsmith
is a gm
based engine that runs on top of either Graphics Magick or Image Magick.
Requirements: Either Graphics Magick or Image Magick must be installed on your machine.
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.
Image Magick is implicitly discovered. However, you can explicitly use it via engineOpts
{
engineOpts: {
imagemagick: true
}
}
Key differences: gmsmith
allows for configuring image quality whereas others do not.
In this example, we are using the alt-diagonal
algorithm to guarantee no overlap if images overflow.
Configuration:
{
imgName: 'sprite.png',
cssName: 'sprite.styl',
algorithm: 'alt-diagonal'
}
Output:
In this example, we are using the phantomjssmith
engine as an alternative to the pixelsmith
default.
Requirements:
Install phantomjssmith
to our node_modules
via npm install
.
npm install phantomjssmith
Alternatively, we can use --save
or --save-dev
to save to our package.json's dependencies
or devDependenices
.
npm install phantomjssmith --save # Updates {"dependencies": {"phantomjssmith": "1.2.3"}}
npm install phantomjssmith --save-dev # Updates {"devDependencies": {"phantomjssmith": "1.2.3"}}
Configuration:
// var phantomjssmith = require('phantomjssmith');
{
imgName: 'sprite.png',
cssName: 'sprite.styl',
engine: phantomjssmith
}
Output:
The padding
option allows for inserting spacing between images.
Configuration:
{
imgName: 'sprite.png',
cssName: 'sprite.styl',
padding: 20 // Exaggerated for visibility, normal usage is 1 or 2
}
Output:
In this example, we will use generate a normal and retina spritesheet via the retinaSrcFilter
and retinaImgName
parameters.
Configuration:
{
// This will filter out `fork@2x.png`, `github@2x.png`, ... for our retina spritesheet
// The normal spritesheet will now receive `fork.png`, `github.png`, ...
retinaSrcFilter: ['images/*@2x.png'],
imgName: 'sprite.png',
retinaImgName: 'sprite@2x.png',
cssName: 'sprite.styl'
}
Normal spritesheet:
Retina spritesheet:
In this example, we will use cssTemplate
with a handlebars
template to generate CSS that uses :before
selectors.
Template:
Configuration:
{
imgName: 'sprite.png',
cssName: 'sprite.css',
cssTemplate: 'handlebarsStr.css.handlebars'
}
Output:
.icon-fork:before {
display: block;
background-image: url(sprite.png);
background-position: 0px 0px;
width: 32px;
height: 32px;
}
.icon-github:before {
/* ... */
In this example, we will extend the SCSS template to provide minimal variables. The JSON at the front comes from the original template and is required to provide consistent casing and default options.
Different block sections for each template are documented in:
https://github.com/twolfson/spritesheet-templates
Template:
Configuration:
{
imgName: 'sprite.png',
cssName: 'sprite.scss',
cssTemplate: 'handlebarsInheritance.scss.handlebars'
}
Output:
$fork: (0px, 0px, 0px, 0px, 32px, 32px, 64px, 64px, 'sprite.png', 'fork', );
$github: (32px, 0px, -32px, 0px, 32px, 32px, 64px, 64px, 'sprite.png', 'github', );
$twitter: (0px, 32px, 0px, -32px, 32px, 32px, 64px, 64px, 'sprite.png', 'twitter', );
$spritesheet-sprites: ($fork, $github, $twitter, );
$spritesheet: (64px, 64px, 'sprite.png', $spritesheet-sprites, );
/* ... */
In this example, we will use cssTemplate
with a custom function that generates YAML.
Configuration:
// var yaml = require('js-yaml');
{
imgName: 'sprite.png',
cssName: 'sprite.yml',
cssTemplate: function (data) {
// Convert sprites from an array into an object
var spriteObj = {};
data.sprites.forEach(function (sprite) {
// Grab the name and store the sprite under it
var name = sprite.name;
spriteObj[name] = sprite;
// Delete the name from the sprite
delete sprite.name;
});
// Return stringified spriteObj
return yaml.safeDump(spriteObj);
}
}
Output:
fork:
x: 0
'y': 0
width: 32
height: 32
source_image: /home/todd/github/gulp.spritesmith/docs/images/fork.png
image: sprite.png
total_width: 64
total_height: 64
escaped_image: sprite.png
offset_x: -0.0
offset_y: -0.0
px:
x: 0px
'y': 0px
offset_x: 0px
offset_y: 0px
height: 32px
width: 32px
total_height: 64px
total_width: 64px
github:
# ...
gulp.spritesmith
doesn't directly support cache busting but gulp-spritesmash
is a plugin that takes gulp.spritesmith's
output and generates cache busted filenames and CSS URLs. Here's an example usage:
https://github.com/MasterOfMalt/gulp-spritesmash
var gulp = require('gulp');
var buffer = require('vinyl-buffer');
var spritesmash = require('gulp-spritesmash');
var spritesmith = require('gulp.spritesmith');
gulp.task('sprite', function () {
return gulp.src('images/*.png', {encoding: false})
.pipe(spritesmith({
imgName: 'sprite.png',
cssName: 'sprite.css'
}))
.pipe(buffer())
.pipe(spritesmash());
.pipe(gulp.dest('path/to/output/', {encoding: false}));
});
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 npm run lint
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.