gulp.spritesmith-multi

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

Example

1var gulp = require('gulp')
2var spritesmith = require('gulp.spritesmith-multi')
3
4gulp.task('default', ['clean'], function () {
5  return gulp.src('default/**/*.png')
6    .pipe(spritesmith())
7    .on('error', function (err) {
8      console.log(err)
9    })
10    .pipe(gulp.dest('build'))
11})
12
13gulp.task('watch', ['default'], function (cb) {
14  gulp.watch('default/**/*.png', ['default'])
15})
16

input:

⌘ tree sp
sp
├── hover
│   ├── sprite1--hover.png
│   ├── sprite1--hover@2x.png
│   ├── sprite1.png
│   ├── sprite1@2x.png
│   ├── sprite2.png
│   ├── sprite2@2x.png
│   ├── sprite3.png
│   └── sprite3@2x.png
├── normal
│   ├── sprite1.png
│   ├── sprite2.png
│   └── sprite3.png
└── retina
    ├── sprite1.png
    ├── sprite1@2x.png
    ├── sprite2.png
    ├── sprite2@2x.png
    ├── sprite3.png
    └── sprite3@2x.png

output:

⌘ tree build/
build/
├── hover.css
├── hover.png
├── hover@2x.png
├── normal.css
├── normal.png
├── retina.css
├── retina.png
└── retina@2x.png

hover.css

1.sp-hover {
2  background-image: url(hover.png)
3}
4
5@media (-webkit-min-device-pixel-ratio: 2),
6       (min-resolution: 192dpi) {
7  .sp-hover {
8    background-image: url(hover@2x.png)
9    background-size: 150px 200px
10  }
11}
12
13.sp-hover__sprite1:hover {
14  background-position: -100px 0px
15  width: 50px
16  height: 50px
17}
18.sp-hover__sprite1 {
19  background-position: -100px -50px
20  width: 50px
21  height: 50px
22}
23.sp-hover__sprite2 {
24  background-position: -100px -100px
25  width: 50px
26  height: 50px
27}
28.sp-hover__sprite3 {
29  background-position: 0px 0px
30  width: 100px
31  height: 200px
32}

Continuing the pipeline

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

1gulp.task('sprite', ['clean'], function () {
2  var merge = require('merge-stream')
3  var imagemin = require('gulp-imagemin')
4  var csso = require('gulp-csso')
5
6  // Generate our spritesheet
7  var spriteData = gulp.src('default/**/*.png')
8    .pipe(spritesmith({
9      spritesmith: function (options) {
10        options.imgPath = '../images/' + options.imgName
11      }
12    }))
13
14  // Pipe image stream through image optimizer and onto disk
15  var imgStream = spriteData.img
16    .pipe(imagemin())
17    .pipe(gulp.dest('build/images'))
18
19  // Pipe CSS stream through CSS optimizer and onto disk
20  var cssStream = spriteData.css
21    .pipe(csso())
22    .pipe(gulp.dest('build/css'))
23
24  // Return a merged stream to handle both `end` events
25  return merge(imgStream, cssStream)
26})
27
28

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:

1var options = {
2  imgName: sprite + '.png',
3  cssName: sprite + '.css',
4  cssTemplate: builtin.css,
5  cssSpritesheetName: 'sp-' + sprite,
6}
7

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.

1var gulp = require('gulp')
2var path = require('path')
3var spritesmith = require('..')
4var util = spritesmith.util
5
6gulp.task('theme', ['clean'], function () {
7  var opts = {
8    spritesmith: function (options, sprite, icons){
9      if (sprite.indexOf('hover--') !== -1) {
10        options.cssTemplate = themeTemplate
11      }
12      return options
13    },
14  }
15  var themeTemplate = util.createTemplate(
16    path.join(__dirname, 'template', 'css.hbs'),
17    [addTheme, util.addPseudoClass]
18  )
19  function addTheme(data) {
20    var info = data.spritesheet_info
21    var match = info.name.match(/hover--(\w+)/)
22    data.theme = match && match[1]
23  }
24  return gulp.src('sp/**/*.png')
25    .pipe(spritesmith(opts))
26    .pipe(gulp.dest('build'))
27})
28

Input:

The custom template

1.{{{theme}}} .sp-hover {
2  background-image: url({{{spritesheet.escaped_image}}});
3}
4
5{{#if retina_spritesheet}}
6@media (-webkit-min-device-pixel-ratio: 2),
7       (min-resolution: 192dpi) {
8  .{{{theme}}} .sp-hover {
9    background-image: url({{{retina_spritesheet.escaped_image}}});
10    background-size: {{spritesheet.px.width}} {{spritesheet.px.height}};
11  }
12}
13{{/if}}
14
15{{#each sprites}}
16.sp-hover__{{{name}}}{{pseudo_class}} {
17  background-position: {{px.offset_x}} {{px.offset_y}};
18  width: {{px.width}};
19  height: {{px.height}};
20}
21{{/each}}
22

Icons

⌘ tree sp/hover*
sp/hover
├── sprite1--hover.png
├── sprite1--hover@2x.png
├── sprite1.png
├── sprite1@2x.png
├── sprite2.png
├── sprite2@2x.png
├── sprite3.png
└── sprite3@2x.png
sp/hover--theme
├── sprite1--hover.png
├── sprite1--hover@2x.png
├── sprite1.png
├── sprite1@2x.png
├── sprite2.png
├── sprite2@2x.png
├── sprite3.png
└── sprite3@2x.png

Output:

⌘ tree build/
build/
├── hover--theme.css
├── hover--theme.png
├── hover--theme@2x.png
├── hover.css
├── hover.png
├── hover@2x.png
├── normal.css
├── normal.png
├── retina.css
├── retina.png
└── retina@2x.png

hover--theme.css

1.theme .sp-hover {
2  background-image: url(hover--theme.png);
3}
4
5@media (-webkit-min-device-pixel-ratio: 2),
6       (min-resolution: 192dpi) {
7  .theme .sp-hover {
8    background-image: url(hover--theme@2x.png);
9    background-size: 150px 200px;
10  }
11}
12
13.sp-hover__sprite1:hover {
14  background-position: -100px 0px;
15  width: 50px;
16  height: 50px;
17}
18.sp-hover__sprite1 {
19  background-position: -100px -50px;
20  width: 50px;
21  height: 50px;
22}
23.sp-hover__sprite2 {
24  background-position: -100px -100px;
25  width: 50px;
26  height: 50px;
27}
28.sp-hover__sprite3 {
29  background-position: 0px 0px;
30  width: 100px;
31  height: 200px;
32}
33

Retina support

All retina icon files should be named like xxx@2x.png.

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.

1var gulp = require('gulp')
2var spritesmith = require('..')
3
4gulp.task('responsive-css', ['clean'], function () {
5  var opts = {
6    spritesmith: {
7      cssTemplate: spritesmith.builtin.responsiveCss,
8    },
9  }
10  return gulp.src('responsive-css/**/*.png')
11    .pipe(spritesmith(opts))
12    .pipe(gulp.dest('build'))
13})

input:

⌘ tree responsive-css
responsive-css
├── hover
│   ├── sprite1--hover.png
│   ├── sprite1--hover@2x.png
│   ├── sprite1.png
│   ├── sprite1@2x.png
│   ├── sprite2.png
│   ├── sprite2@2x.png
│   ├── sprite3.png
│   └── sprite3@2x.png
├── normal
│   ├── sprite1.png
│   ├── sprite2.png
│   └── sprite3.png
└── retina
    ├── sprite1.png
    ├── sprite1@2x.png
    ├── sprite2.png
    ├── sprite2@2x.png
    ├── sprite3.png
    └── sprite3@2x.png

output:

⌘ tree build/
build
├── hover.css
├── hover.png
├── hover@2x.png
├── normal.css
├── normal.png
├── retina.css
├── retina.png
└── retina@2x.png

hover.css

1.sp-hover {
2  background-image: url(hover.png);
3}
4
5@media (-webkit-min-device-pixel-ratio: 2),
6       (min-resolution: 192dpi) {
7  .sp-hover {
8    background-image: url(hover@2x.png);
9  }
10}
11
12.sp-hover__sprite1:hover {
13  background-position: 100% 0;
14  background-size: 300%;
15  width: 50px;
16  height: 50px;
17}
18.sp-hover__sprite1 {
19  background-position: 100% 33.33333%;
20  background-size: 300%;
21  width: 50px;
22  height: 50px;
23}
24.sp-hover__sprite2 {
25  background-position: 100% 66.66667%;
26  background-size: 300%;
27  width: 50px;
28  height: 50px;
29}
30.sp-hover__sprite3 {
31  background-position: 0 0;
32  background-size: 150%;
33  width: 100px;
34  height: 200px;
35}

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 name--pseduoClass@2x.png.

exports.builtin

Type: Object

Templates provided by default.

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