In the BS2 days, our sites exclusively used sprites–two raster images with one for “regular” browsers and another for retina, each of which contained the icons for the site. That setup allowed only two images to be loaded for all icons on the site, and the icon displayed would be set with CSS classes. However, the issue with sprites was that whenever you wanted to add a new one, you had to open the original AI file, add the icon, save out the image (twice), and then rework the CSS to allow for the new image.
Our BS3 sites added on both SpriteSmith and iconfonts. Spritesmith allowed for much easier use of sprites without the need for editing an AI file every time–you only needed to add the 1x (normal size) and 2x (retina size) of each icon, and spritesmith would do the rest with the site build. Iconfonts were also added at the time, which took things even a step further–you simply needed to add an svg file into a specific folder, and then you could change the color, size, etc. of the icon using CSS.
Our most recent BS4 sites only have iconfonts installed by default, and this will cover most uses. However, you may come across a situation where you need to use a hard-coded icon with multiple colors, or a very complex design–neither of which are allowed by iconfonts, which can only be svg files, with only one path, and only one color. In cases like that, you can add spritesmith back in. This method will work for both gulp 3 and gulp 4 sites (normal bootstrap 4 sites, and new showcase sites) without much or any modification.
Rather than installing sprites, for example if you have a much larger image that needs two sizes, if it’s hard-coded you can use this image tag instead. It has spaces for two versions of the iamge, one for regular and one for retina screens. This image setup works for any site, so if you have a very old site that it would be too much of a pain to install spritesmith on, you can use this instead.
<img srcset="/assets/img/sprite-leftarrow-2x.png 2x, /assets/img/sprite-leftarrow.png 1x" src="/assets/img/sprite-leftarrow.png">
But if you have a bunch of images that work this way, it’s still probably better to use sprites!
How To
Install with iTerm
In iTerm, while in the development folder of your site, run npm install gulp.spritesmith
JSON/Build Files
package.json
Once this is complete, you should be able to confirm in your package.json file that gulp.spritesmith has been added to the devDependencies section. (You may need to move it from its own dependencies section into devDependencies.)
gulpfile.js
In the gulpfile.js, add
spritesmith = require('gulp.spritesmith'),into the list of plugin variables at the top.Further down in the gulpfile.js, there may be a section for sprites already. You can overwrite it with what’s included below to make sure it’s up-to-date. I usually put it below Images.
// ============= Sprites ============= //
gulp.task('sprite', function(cb) {
var spriteData = gulp.src('./src/images/sprites/*.png')
.pipe(plumber({ errorHandler: notify.onError("Error: <%= error.message %>") }))
.pipe(spritesmith({
imgName: 'sprite.png',
cssName: 'sprite.css',
imgPath: '../img/sprite.png',
padding: 2,
retinaSrcFilter: './src/images/sprites/*-2x.png',
retinaImgName:'sprites-2x.png',
retinaImgPath: '../img/sprites-2x.png',
cssOpts: {
cssSelector: function(sprite) {
// `item` has `x`, `y`, `width`, `height`, `name`, `image`, and more
// It is suggested to `console.log` output
return '.sprite-' + sprite.name +', '+'.sprite-before-'+sprite.name+':before, '+'.sprite-after-'+sprite.name+':after';
}
}
}));
spriteData.img.pipe(gulp.dest('./src/images/'));
spriteData.css.pipe(rename({extname: '.scss'})).pipe(gulp.dest('./src/scss/'));
return spriteData;
});
- At the bottom of the gulpfile.js, there are two pieces of the task watcher that should include sprite references, you can leave them as-is. The one that is commented out which probably won’t be there is included below. (The first one is included as part of the images piece which can be left as-is.)
// inside of gulp watch function
// Sprites
//gulp.watch(["./src/images/sprites/*-2x.png" ], ['sprite']);
CSS
helpers.scss
In your scss > custom > helpers.scss, add the included code below to make sure that all sprites are displayed properly.
span[class^="sprite-"],
span[class*=" sprite-"]{
display: inline-block;
vertical-align: vertical;
}
// alternative setup (original)
i,
span[class^="sprite-"],
span[class*=" sprite-"],
span[class^="icon-"],
span[class*=" icon-"] {
display: inline-block;
vertical-align: top;
}
main.scss
Near the bottom of main.scss, add @import "sprite"; to ensure that the new sprite file generated by the gulpfile is pulled in.
Folder Structure
Create a new folder, sprites, under the path src > images > sprites, where you can put all your sprite PNG files. Make sure to have a normal and 2x file for each.
Make sure to save all files!
Checking Installation
Run gulp sprite in your iTerm, and then check inside the images folder and scss folder. Several sprite files should have been generated.
Run gulp in iterm again to make sure that the installation went through OK.
Run gulp sprite again to create the actual sprite files now that everything is functional!
Using It
You can set up a sprite in your HTML like this:
<span class="sprite-chromelogo" aria-hidden="true"></span>
Example Sites
- CHROME Federal Credit Union (BS4 Showcase+ site that uses sprites for the pin icons in the footer menu)
Tags: sprites, bs2, bs3, bs4