gulp.spritesmith-multi

A wrapper for gulp.spritesmith to generate multiple sprites and stylesheets.

Example

var gulp = require('gulp')
var spritesmith = require('gulp.spritesmith-multi')

gulp.task('default', ['clean'], function () {
  return gulp.src('default/**/*.png')
    .pipe(spritesmith())
    .on('error', function (err) {
      console.log(err)
    })
    .pipe(gulp.dest('build'))
})

gulp.task('watch', ['default'], function (cb) {
  gulp.watch('default/**/*.png', ['default'])
})

input:

⌘ tree sp
sp
├── hover
│   ├── sprite1--hover.png
│   ├── [email protected]
│   ├── sprite1.png
│   ├── [email protected]
│   ├── sprite2.png
│   ├── [email protected]
│   ├── sprite3.png
│   └── [email protected]
├── normal
│   ├── sprite1.png
│   ├── sprite2.png
│   └── sprite3.png
└── retina
    ├── sprite1.png
    ├── [email protected]
    ├── sprite2.png
    ├── [email protected]
    ├── sprite3.png
    └── [email protected]

output:

⌘ tree build/
build/
├── hover.css
├── hover.png
├── [email protected]
├── normal.css
├── normal.png
├── retina.css
├── retina.png
└── [email protected]

hover.css

.sp-hover {
  background-image: url(hover.png)
}

@media (-webkit-min-device-pixel-ratio: 2),
       (min-resolution: 192dpi) {
  .sp-hover {
    background-image: url([email protected])
    background-size: 150px 200px
  }
}

.sp-hover__sprite1:hover {
  background-position: -100px 0px
  width: 50px
  height: 50px
}
.sp-hover__sprite1 {
  background-position: -100px -50px
  width: 50px
  height: 50px
}
.sp-hover__sprite2 {
  background-position: -100px -100px
  width: 50px
  height: 50px
}
.sp-hover__sprite3 {
  background-position: 0px 0px
  width: 100px
  height: 200px
}

Continuing the pipeline

You can continue the pipeline the way the original gulp.spritesmith support.

gulp.task('sprite', ['clean'], function () {
  var merge = require('merge-stream')
  var imagemin = require('gulp-imagemin')
  var csso = require('gulp-csso')

  // Generate our spritesheet
  var spriteData = gulp.src('default/**/*.png')
    .pipe(spritesmith({
      spritesmith: function (options) {
        options.imgPath = '../images/' + options.imgName
      }
    }))

  // Pipe image stream through image optimizer and onto disk
  var imgStream = spriteData.img
    .pipe(imagemin())
    .pipe(gulp.dest('build/images'))

  // Pipe CSS stream through CSS optimizer and onto disk
  var cssStream = spriteData.css
    .pipe(csso())
    .pipe(gulp.dest('build/css'))

  // Return a merged stream to handle both `end` events
  return merge(imgStream, cssStream)
})

Options

to(iconFile)

Specify the name of the sprite into which the given icon should be included

Type: Function, String

If String, you just get one sprite.

By default, icons are grouped by their directory names.

spritesmith

Specify options for each sprite.

Type: Object, Function

The following fields are set by default:

var options = {
  imgName: sprite + '.png',
  cssName: sprite + '.css',
  cssTemplate: builtin.css,
  cssSpritesheetName: 'sp-' + sprite,
}

You can override them through this option.

If Function, it receives the default options, the sprite name specified by options.to and the related icon files (vinyl file objects). Modify the options object passed in, or return a new one.

Custom templates

The default css template is exports.builtin.css.

To specify custom templates, create a templater through exports.util.createTemplate, and set options.spritesmith.cssTemplate to it.

var gulp = require('gulp')
var path = require('path')
var spritesmith = require('..')
var util = spritesmith.util

gulp.task('theme', ['clean'], function () {
  var opts = {
    spritesmith: function (options, sprite, icons){
      if (sprite.indexOf('hover--') !== -1) {
        options.cssTemplate = themeTemplate
      }
      return options
    },
  }
  var themeTemplate = util.createTemplate(
    path.join(__dirname, 'template', 'css.hbs'),
    [addTheme, util.addPseudoClass]
  )
  function addTheme(data) {
    var info = data.spritesheet_info
    var match = info.name.match(/hover--(\w+)/)
    data.theme = match && match[1]
  }
  return gulp.src('sp/**/*.png')
    .pipe(spritesmith(opts))
    .pipe(gulp.dest('build'))
})

Input:

The custom template

.{{{theme}}} .sp-hover {
  background-image: url({{{spritesheet.escaped_image}}});
}

{{#if retina_spritesheet}}
@media (-webkit-min-device-pixel-ratio: 2),
       (min-resolution: 192dpi) {
  .{{{theme}}} .sp-hover {
    background-image: url({{{retina_spritesheet.escaped_image}}});
    background-size: {{spritesheet.px.width}} {{spritesheet.px.height}};
  }
}
{{/if}}

{{#each sprites}}
.sp-hover__{{{name}}}{{pseudo_class}} {
  background-position: {{px.offset_x}} {{px.offset_y}};
  width: {{px.width}};
  height: {{px.height}};
}
{{/each}}

Icons

⌘ tree sp/hover*
sp/hover
├── sprite1--hover.png
├── [email protected]
├── sprite1.png
├── [email protected]
├── sprite2.png
├── [email protected]
├── sprite3.png
└── [email protected]
sp/hover--theme
├── sprite1--hover.png
├── [email protected]
├── sprite1.png
├── [email protected]
├── sprite2.png
├── [email protected]
├── sprite3.png
└── [email protected]

Output:

⌘ tree build/
build/
├── hover--theme.css
├── hover--theme.png
├── [email protected]
├── hover.css
├── hover.png
├── [email protected]
├── normal.css
├── normal.png
├── retina.css
├── retina.png
└── [email protected]

hover--theme.css

.theme .sp-hover {
  background-image: url(hover--theme.png);
}

@media (-webkit-min-device-pixel-ratio: 2),
       (min-resolution: 192dpi) {
  .theme .sp-hover {
    background-image: url([email protected]);
    background-size: 150px 200px;
  }
}

.sp-hover__sprite1:hover {
  background-position: -100px 0px;
  width: 50px;
  height: 50px;
}
.sp-hover__sprite1 {
  background-position: -100px -50px;
  width: 50px;
  height: 50px;
}
.sp-hover__sprite2 {
  background-position: -100px -100px;
  width: 50px;
  height: 50px;
}
.sp-hover__sprite3 {
  background-position: 0px 0px;
  width: 100px;
  height: 200px;
}

Retina support

All retina icon files should be named like [email protected].

Responsive CSS support

Responsive CSS sprites are able to be resized in relative length units such as rem which is practical in creating perfectly scalable layout.

You can use a builtin template exports.builtin.responsiveCss to generate responsive CSS sprites.

var gulp = require('gulp')
var spritesmith = require('..')

gulp.task('responsive-css', ['clean'], function () {
  var opts = {
      cssTemplate: spritesmith.builtin.responsiveCss,
    },
  }
  return gulp.src('responsive-css/**/*.png')
    .pipe(spritesmith(opts))
    .pipe(gulp.dest('build'))
})

input:

⌘ tree responsive-css
responsive-css
├── hover
│   ├── sprite1--hover.png
│   ├── [email protected]
│   ├── sprite1.png
│   ├── [email protected]
│   ├── sprite2.png
│   ├── [email protected]
│   ├── sprite3.png
│   └── [email protected]
├── normal
│   ├── sprite1.png
│   ├── sprite2.png
│   └── sprite3.png
└── retina
    ├── sprite1.png
    ├── [email protected]
    ├── sprite2.png
    ├── [email protected]
    ├── sprite3.png
    └── [email protected]

output:

⌘ tree build/
build
├── hover.css
├── hover.png
├── [email protected]
├── normal.css
├── normal.png
├── retina.css
├── retina.png
└── [email protected]

hover.css

.sp-hover {
  background-image: url(hover.png);
}

@media (-webkit-min-device-pixel-ratio: 2),
       (min-resolution: 192dpi) {
  .sp-hover {
    background-image: url([email protected]);
  }
}

.sp-hover__sprite1:hover {
  background-position: 100% 0;
  background-size: 300%;
  width: 50px;
  height: 50px;
}
.sp-hover__sprite1 {
  background-position: 100% 33.33333%;
  background-size: 300%;
  width: 50px;
  height: 50px;
}
.sp-hover__sprite2 {
  background-position: 100% 66.66667%;
  background-size: 300%;
  width: 50px;
  height: 50px;
}
.sp-hover__sprite3 {
  background-position: 0 0;
  background-size: 150%;
  width: 100px;
  height: 200px;
}

Though there are default width and height in the CSS rules, you can override them and the background image will be resized automatically.

Utils

exports.util

Type: Object

Methods to work with.

createTemplate(tplInfo, filter)

Create a templater.

tplInfo

Specify template.

Type: Object

• tplInfo.file: the file path of the handlebars template
• tplInfo.source: the contents of the template

Either one of them should be specified.

If tplInfo is String, it is treated as a file path.

filter

Specify data for the template.

If Array, you are specifying an array of filters.

If Object, it will be mixed into the default data.

If Function, you can modify the default data object, or just return a new one.

addPseudoClass

A template data filter to support generating pseudo classes.

If the icon file is something like name--pseduoClass.png, .sp-sprite__name:pseduoClass is created in the css, rather than .sp-sprite__name--pseduoClass.

NOTE: for retina icons, you should name them like [email protected].

exports.builtin

Type: Object

Templates provided by default.

Pick one of them, and set options.spritesmith.cssTemplate to apply it.