css-sprite
A css sprite generator.
Generates sprites and proper css files out of a directory of images.
Supports retina sprites.
Can inline base64 encoded sprites.
sprity
css-sprite is now calledVersion 1.0.0 had so many changes, that I decided to also change the name to something a little bit more catchy. So css-sprite
is called sprity from now on. css-sprite will be deprecated and no development will be done here anymore.
Requirements
Starting with version 0.9 css-sprite
has no external dependencies
Install
Install with npm
npm install css-sprite --save
If you want to use css-sprite
on your cli install with:
npm install css-sprite -g
Command Line Interface
Usage: css-sprite <out> <src>... [options] out path of directory to write sprite file tosrc glob strings to find source images to put into the sprite Options: -b, --base64 create css with base64 encoded sprite -c, --css-image-path http path to images on the web server [../images] -f, --format output format of the sprite [png] -n, --name name of sprite file without file extension [sprite] -p, --processor output format of the css. one of css, less, sass, scss or stylus [css] -t, --template output template file, overrides processor option -r, --retina generate both retina and standard sprites. src images have to be in retina resolution -s, --style file to write css to,
Programatic usage
var sprite = require('css-sprite');
sprite.create(options, cb);
Options
- src: Array or string of globs to find source images to put into the sprite. [required]
- out: path of directory to write sprite file to [process.cwd()]
- base64: when true instead of creating a sprite writes base64 encoded images to css (css file will be written to
<out>
) - cssPath: http path to images on the web server (relative to css path or absolute) [../images]
- format format of the generated sprite (png or jpg). By default uses png.
- name: name of the sprite file without file extension [sprite]
- processor: output format of the css. one of css, less, sass, scss or stylus [css]
- template: output template file, overrides processor option (must be a mustache template)
- retina: generate both retina and standard sprites. src images have to be in retina resolution
- background background color of the sprite in hex. Defaults to #FFFFFF
- cachebuster appends a "cache buster" to the background image in the form "?<...>" (random) [false]
- style: file to write css to, if omitted no css is written
- margin: margin in px between tiles. (Use an even number if generating retina sprites). [4]
- opacity background opacity of the sprite between 0 and 100. Defaults to 0 when png or 100 when jpg
- orientation: orientation of the sprite image (vertical|horizontal|binary-tree) [vertical]
- prefix: prefix for the class name used in css (without .) [icon]
- sort: enable/disable sorting of layout [true]
- interpolation Interpolation algorithm used when scaling retina images to standard definition. Possible values are
nearest-neighbor
,moving-average
,linear
,grid
,cubic
,lanczos
. Defaults togrid
.
Example
var sprite = ;sprite;
Gulp
Usage withvar gulp = ;var gulpif = ;var sprite = stream; // generate sprite.png and _sprite.scssgulp;// generate scss with base64 encoded imagesgulp;
Options to use css-sprite
with Gulp are the same as for the sprite.create
function with the exception of src
and out
.
Grunt
Usage withAdd css-sprite
as a dependency to your grunt project and then use something like this in your gruntfile.js
:
module { // Project configuration. grunt; // Load the plugin that provides the "css-sprite" task. grunt; // Default task(s). grunt;};
Options to use css-sprite
with Grunt are the same as for the sprite.create
function with the exception of src
and out
.
sass / less / stylus
Usage withscss example
; // the generated style file (sprite.scss) // camera icon (camera.png in src directory) .icon-camera // cart icon (cart.png in src directory) .icon-cart
sass example
// camera icon (camera.png in src directory) // cart icon (cart.png in src directory)
less example
'sprite'; // the generated style file (sprite.less) // camera icon (camera.png in src directory) .icon-camera .sprite@camera; // cart icon (cart.png in src directory) .icon-cart .sprite@cart;
stylus example
@import 'sprite' // the generated style file (sprite.styl) // camera icon (camera.png in src directory).icon-camera $camera) // cart icon (cart.png in src directory).icon-cart $cart)
Using your own template
To use your own mustache template for style file creation pass in the -t option followed by the template path. The following variables are available in the mustache template:
- items -- array of objects with the sprite tiles
- name -- name of the tile
- x -- x position
- y -- y position
- width
- height
- offset_x -- x offset within the sprite
- offset_y -- y offset within the sprite
- class -- class name of the tile
- px -- object with pixel values instead of raw data (e.g width: '250px')
- x, y, offset_x, offset_y, height, width, total_height, total_width
- sprite -- object with information about the sprite itself
- name -- name of the sprite
- image -- css path to sprite or base64 encode string
- escaped_image -- escaped css path to sprite or base64 encode string
- class -- class name of the sprite
- retina -- object with information about the retina sprite
- name -- name of the retina sprite
- image -- css path to retina sprite
- escaped_image -- escaped css path to retina sprite
- class -- class name of the retina sprite
- total_width -- height of the retina sprite (for background-size)
- total_height -- width of the retina sprite (for background-size)
- px -- object with pixel values
- total_width, total_height
Please have a look at the included templates to see how they work.