Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bin
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

readme.md

css-sprite

NPM version Build Status Coverage Status Code Climate Dependencies

A css sprite generator.

Generates sprites and proper css files out of a directory of images.

Supports retina sprites.

Can inline base64 encoded sprites.

css-sprite is now called sprity

Version 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 to
src     glob strings to find source images to put into the sprite

Options:
    -b, --base64           create css with base64 encoded sprite (css file will be written to <out>)
    -c, --css-image-path   http path to images on the web server (relative to css path or absolute path)  [../images]
    -f, --format           output format of the sprite (png or jpg)  [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, if omitted no css is written
    -w, --watch            continuously create sprite
    --background           background color of the sprite in hex  [#FFFFFF]
    --cachebuster          appends a "cache buster" to the background image in the form "?<...>" (random)  [false]
    --margin               margin in px between tiles  [4]
    --interpolation        Interpolation algorithm used when scaling retina images (nearest-neighbor|moving-average|linear|grid|cubic|lanczos)
    --opacity              background opacity of the sprite. defaults to 0 when png or 100 when jpg  [0]
    --orientation          orientation of the sprite image (vertical|horizontal|binary-tree)  [vertical]
    --prefix               prefix for the class name used in css (without .)
    --no-sort              disable sorting of layout

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 to grid.

Example

var sprite = require('css-sprite');
sprite.create({
  src: ['./src/img/*.png'],
  out: './dist/img'
  name: 'sprites',
  style: './dist/scss/_sprites.scss',
  cssPath: '../img',
  processor: 'scss'
}, function () {
  console.log('done');
});

Usage with Gulp

var gulp = require('gulp');
var gulpif = require('gulp-if');
var sprite = require('css-sprite').stream;

// generate sprite.png and _sprite.scss
gulp.task('sprites', function () {
  return gulp.src('./src/img/*.png')
    .pipe(sprite({
      name: 'sprite',
      style: '_sprite.scss',
      cssPath: './img',
      processor: 'scss'
    }))
    .pipe(gulpif('*.png', gulp.dest('./dist/img/'), gulp.dest('./dist/scss/')))
});
// generate scss with base64 encoded images
gulp.task('base64', function () {
  return gulp.src('./src/img/*.png')
    .pipe(sprite({
      base64: true,
      style: '_base64.scss',
      processor: 'scss'
    }))
    .pipe(gulp.dest('./dist/scss/'));
});

Options to use css-sprite with Gulp are the same as for the sprite.create function with the exception of src and out.

Usage with Grunt

Add css-sprite as a dependency to your grunt project and then use something like this in your gruntfile.js:

module.exports = function(grunt) {

  // Project configuration.
  grunt.initConfig({
    css_sprite: {
      options: {
        'cssPath': '../images',
        'processor': 'css',
        'orientation': 'vertical',
        'margin': 4
      },
      sprite: {
        options: {
          'style': 'dest/css/sprite.css'
        },
        src: ['src/images/*', 'src/images2/*'],
        dest: 'dest/images/sprite.png',
      },
      base64: {
        options: {
          'base64': true
        },
        src: ['src/images/*'],
        dest: 'dest/scss/base64.css',
      }
    }
  });

  // Load the plugin that provides the "css-sprite" task.
  grunt.loadNpmTasks('css-sprite');

  // Default task(s).
  grunt.registerTask('default', ['css_sprite']);
};

Options to use css-sprite with Grunt are the same as for the sprite.create function with the exception of src and out.

Usage with sass / less / stylus

scss example

@import 'sprite'; // the generated style file (sprite.scss)

// camera icon (camera.png in src directory)
.icon-camera {
  @include sprite($camera);
}

// cart icon (cart.png in src directory)
.icon-cart {
  @include sprite($cart);
}

sass example

@import 'sprite' // the generated style file (sprite.sass)

// camera icon (camera.png in src directory)
.icon-camera
  +sprite($camera)

// cart icon (cart.png in src directory)
.icon-cart
  +sprite($cart)

less example

@import '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
  sprite($camera)

// cart icon (cart.png in src directory)
.icon-cart
  sprite($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.

You can’t perform that action at this time.