grunt-spritesmith
Advanced tools
Grunt task for converting a set of images into a spritesheet and corresponding CSS variables.
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;
...
As of grunt-spritesmith@4.5.0, retina spritesheets/templates are supported. See the Retina parameters section for more information.
grunt-spritesmith is supported and tested on Windows, Linux, and Mac OS X.
grunt-spritesmith?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 #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 to enable usage of streaming outputs from engines.
grunt-spritesmith can be installed via npm: npm install grunt-spritesmith
Then, add and configure it to your Gruntfile.js:
module.exports = function (grunt) {
// Configure grunt
grunt.initConfig({
sprite:{
all: {
src: 'path/to/your/sprites/*.png',
dest: '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 "destination/of/spritesheet.png", "destination/of/sprites.css" 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 supports the following parameters:
String|String[] - Images to use as sprites in spritesheet
sprites/*.png or an array of files ['sprite1.png', sprite2.png']String - Output location for generated spritesheet
path/to/output/spritesheet.pngString - Output location for generated CSS
path/to/output/sprites.cssString - Optional override for spritesheet path specified in CSS
../sprite.png is given, then the CSS will have:
background-image: url(../sprite.png);Number - Padding to place to right and bottom between sprites
String - Algorithm to use for positioning sprites in spritesheet
binary-tree which yields the best possible packingMixed - Options to pass through to algorithm
{algorithmOpts: {sort: false}}
String - spritesmith engine to use
pixelsmith, a node based enginenpm installObject - Options to pass through to engine for settings
phantomjssmith accepts timeout via {engineOpts: {timeout: 10000}}Object - Options to pass through to engine uring export
gmsmith supports quality via {imgOpts: {quality: 75}}String - CSS format to use
destCss' extension
.styl -> stylusString|Function - CSS template to use for rendering output CSS
cssFormatString is provided, it must be a path to a handlebars template
Function is provided, it must have a signature of function (data)
Object - Container for helpers to register to handlebars for our template
{half: function (num) { return num/2; } will add a handlebars helper that halves numbersFunction - Mapping function for each filename to CSS variable
String - Name to use for spritesheet related variables in preprocessor templatesObject - Options to pass through to templater
{cssOpts: {functions: false}} skips output of mixinsgrunt-spritesmith supports retina spritesheet generation via retinaSrcFilter and retinaDest. 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.
String|String[] - Images to use for both normal and retina spritesheet
sprites/*.png should capture sprite1.png and sprite1@2x.png@2x suffix over -retina or -2x. There are known ordering issues caused when sharing a - delimiter between sprite names and the retina suffix (see #137)String|String[] - Images to filter out from src for our retina spritesheet
src (e.g. sprite/*@2x.png)src (e.g. src: 'sprite/*.png', retinaSrcFilter: 'sprite/*@2x.png')sprites/*@2x.png will filter out sprite1@2x.png for a separate retina spritesheet
sprite1.png and sprite1@2x.png as a group of normal/retina spritesString - Output location for generated retina spritesheet
path/to/output@2x.png../sprite@2x.png will yield CSS with:
background-image: url(../sprite@2x.png);Number - Padding to place to right and bottom between sprites
String - CSS format to use
destCss' extension
.styl -> stylus_retinaFunction - Mapping function for each filename to CSS variable
$icon-home will have group $icon-home-group)String - Name to use for retina spritesheet related variables in preprocessor templatesString - Name to use for retina groups related variables in preprocessor templatesImages 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.
Object Container for parameters
Object[] - Array of sprite information
String - Name of the sprite file (sans extension)Number - Horizontal position of sprite's left edge in spritesheetNumber - Vertical position of sprite's top edge in spritesheetNumber - Width of spriteNumber - Height of spriteNumber - Width of entire spritesheetNumber - Height of entire spritesheetString - Relative URL path from CSS to spritesheetString - URL encoded imageString - Path to the original sprite fileNumber - Negative value of x. Useful to background-positionNumber - Negative value of y. Useful to background-positionObject - Container for numeric values including px
String - x suffixed with pxString - y suffixed with pxString - width suffixed with pxString - height suffixed with pxString - total_width suffixed with pxString - total_height suffixed with pxString - offset_x suffixed with pxString - offset_y suffixed with pxObject - Information about spritesheet
Number - Width of entire spritesheetNumber - Height of entire spritesheetString - Relative URL path from CSS to spritesheetString - URL encoded imageObject - Container for numeric values including px
String - width suffixed with pxString - height suffixed with pxObject - Container for spritesheet metadata and its representation
String - Prefix for spritesheet variablesObject[] - Array of retina sprite information
sprites (e.g. name, width, source_image)Object - Information about retina spritesheet
spritesheet (e.g. width, px)Object - Container for retina_spritesheet metadata and its representation
String - Prefix for spritesheet variablesObject[] - Array of objects that maps to normal and retina sprites
Object - Container for data about sprite mapping
String - Name to refer to mapping byNumber - Index of corresponding normal/retina sprites from data.sprites/data.retina_spritesObject - Normal sprite from data.sprites that corresponds to our mapping
data.sprites[*] (e.g. name, x, offset_y, px)Object - Retina sprite from data.retina_sprites that corresponds to our mapping
data.retina_sprites[*] (e.g. name, x, offset_y, px)Object - Optional container for metadata about retina_groups and its representation
String - Name for retina_groupsObject - Options passed in via cssOpts in grunt-spritesmith configAn 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
csstemplate, 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.
[node-canvas wiki]: (https://github.com/LearnBoost/node-canvas/wiki/_pages [node-gyp]: https://github.com/TooTallNate/node-gyp/
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 will use the alt-diagonal algorithm to layout sprites in a non-intersecting manner.
Configuration:
{
src: ['fork.png', 'github.png', 'twitter.png'],
dest: 'spritesheet.algorithm.png',
destCss: 'spritesheet.algorithm.styl',
algorithm: 'alt-diagonal'
}
Output:
In this example, we will use the gmsmith engine to support obscure image formats.
Requirements:
Install gmsmith to our node_modules via npm install.
npm install gmsmith
Alternatively, we can use --save or --save-dev to save to our package.json's dependencies or devDependenices.
npm install gmsmith --save # Updates {"dependencies": {"gmsmith": "1.2.3"}}
npm install gmsmith --save-dev # Updates {"devDependencies": {"gmsmith": "1.2.3"}}
Configuration:
{
src: ['fork.png', 'github.png', 'twitter.png'],
dest: 'spritesheet.algorithm.png',
destCss: 'spritesheet.algorithm.styl',
engine: 'gmsmith'
}
Output:
The padding option allows for inserting spacing between images.
Configuration:
{
src: ['fork.png', 'github.png', 'twitter.png'],
dest: 'spritesheet.padding.png',
destCss: 'spritesheet.padding.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 retinaDest parameters.
Configuration:
{
// We have `fork.png`, `fork@2x.png`, ...
src: ['fork*.png', 'github*.png', 'twitter*.png'],
// 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: ['*@2x.png'],
dest: 'spritesheet.retina.png',
retinaDest: 'spritesheet.retina@2x.png',
destCss: 'spritesheet.retina.styl'
}
Normal spritesheet:
Retina spritesheet:
In this example, we will use cssTemplate with a handlebars template to generate CSS that uses :before selectors.
Template:
{{#sprites}}
.icon-{{name}}:before {
display: block;
background-image: url({{{escaped_image}}});
background-position: {{px.offset_x}} {{px.offset_y}};
width: {{px.width}};
height: {{px.height}};
}
{{/sprites}}
Configuration:
{
src: ['fork.png', 'github.png', 'twitter.png'],
dest: 'spritesheet.handlebarsStr.png',
destCss: 'spritesheet.handlebarsStr.css',
cssTemplate: 'handlebarsStr.css.handlebars'
}
Output:
.icon-fork:before {
display: block;
background-image: url(spritesheet.handlebarsStr.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:
{
// Default options
'functions': true,
'variableNameTransforms': ['dasherize']
}
{{#extend "scss"}}
{{#content "sprites"}}
{{#each sprites}}
${{strings.name}}: ({{px.x}}, {{px.y}}, {{px.offset_x}}, {{px.offset_y}}, {{px.width}}, {{px.height}}, {{px.total_width}}, {{px.total_height}}, '{{{escaped_image}}}', '{{name}}', );
{{/each}}
{{/content}}
{{#content "spritesheet"}}
${{spritesheet_info.strings.name_sprites}}: ({{#each sprites}}${{strings.name}}, {{/each}});
${{spritesheet_info.strings.name}}: ({{spritesheet.px.width}}, {{spritesheet.px.height}}, '{{{spritesheet.escaped_image}}}', ${{spritesheet_info.strings.name_sprites}}, );
{{/content}}
{{/extend}}
Configuration:
{
src: ['fork.png', 'github.png', 'twitter.png'],
dest: 'spritesheet.handlebarsInheritance.png',
destCss: 'spritesheet.handlebarsInheritance.css',
cssTemplate: 'handlebarsInheritance.scss.handlebars'
}
Output:
$fork: (0px, 0px, 0px, 0px, 32px, 32px, 64px, 64px, 'spritesheet.handlebarsInheritance.png', 'fork', );
$github: (32px, 0px, -32px, 0px, 32px, 32px, 64px, 64px, 'spritesheet.handlebarsInheritance.png', 'github', );
$twitter: (0px, 32px, 0px, -32px, 32px, 32px, 64px, 64px, 'spritesheet.handlebarsInheritance.png', 'twitter', );
$spritesheet-sprites: ($fork, $github, $twitter, );
$spritesheet: (64px, 64px, 'spritesheet.handlebarsInheritance.png', $spritesheet-sprites, );
/* ... */
In this example, we will use cssTemplate with a custom function that generates YAML.
Configuration:
// var yaml = require('js-yaml');
{
src: ['fork.png', 'github.png', 'twitter.png'],
dest: 'spritesheet.yamlTemplate.png',
destCss: 'spritesheet.yamlTemplate.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: fork.png
image: spritesheet.yamlTemplate.png
total_width: 64
total_height: 64
escaped_image: spritesheet.yamlTemplate.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:
x: 32
# ...
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
Plus and Equals icons were built using the Ubuntu Light typeface.
Copyright (c) 2012 Todd Wolfson
Licensed under the MIT license.
FAQs
Grunt task for converting a set of images into a spritesheet and corresponding CSS variables.
The npm package grunt-spritesmith receives a total of 11,003 weekly downloads. As such, grunt-spritesmith popularity was classified as popular.
We found that grunt-spritesmith demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.