README.old.md

gulp-svg-sprites

Gulp plugin for working with SVGs

Notice - This is a new project with a deliberately minimal feature set. If there's something missing that would help you though, post an issue and we'll try to get it implemented.

Usage

Install it locally to your project.

npm install gulp-svg-sprites

##Screencasts

1. Simple usage
2. Configuration
3. Support for <defs> output (as per Chris Coyiers article)

Example 1 - Sprite Sheet

This will take a bunch of SVGs, create a sprite-sheet out of it (in both SVG & PNG) & write all the CSS for you (including .no-svg prefixes for the fallback)

var gulp = require('gulp');
var svgSprites = require('gulp-svg-sprites');

var svg = svgSprites.svg;
var png = svgSprites.png;

gulp.task('sprites', function () {
    return gulp.src('assets/svg/*.svg')
            .pipe(svg())
            .pipe(gulp.dest("assets"))
            .pipe(png());
});

Example 2 - using <defs>

As explained in this article by Chris Coyier, there's an even better way to use SVGs, if you are not concerned with old versions of IE. Setting the config option defs: true will create the required output for using that technique.

NOTE: when using this mode, you cannot generate a PNG fallback from the SVG output. Trying to do so will cause an error.

var gulp = require('gulp');
var svgSprites = require('gulp-svg-sprites');

var svg = svgSprites.svg;

gulp.task('sprites', function () {
    return gulp.src('assets/svg/*.svg')
            .pipe(svg({defs: true}))
            .pipe(gulp.dest("assets"));
});

Example, with custom class names

You can pass a config object to the svg function that will allow full control over the resulting CSS. For example, say you wanted all of your CSS classes to have -icon suffix, you could do this:

var config = {
    className: ".%f-icon"
};

gulp.task('sprites', function () {
    return gulp.src('assets/svg/*.svg')
            .pipe(svg(config))
            .pipe(gulp.dest("assets"))
            .pipe(png());
});

Which would create class names like this in the the CSS (where facebook was the filename)

.facebook-icon {
	/* css generated here */
}

It's the %f from .%f-icon which gets replaced with the filename of the SVG - This means you can also add prefixes easily as well.

var config = {
    className: ".svg-%f-icon"
};

gulp.task('sprites', function () {
    return gulp.src('assets/svg/*.svg')
            .pipe(svg(config))
            .pipe(gulp.dest("assets"))
            .pipe(png());
});

Which would create:

.svg-facebook-icon {
	/* css generated here */
}

You can also provide a callback function for the class names too. The first argument is the filename, the second is the entire config object

var config = {
    className: function (file, object) {
        return ".svg-" + file;
    }
};

gulp.task('sprites', function () {
    return gulp.src('assets/svg/*.svg')
            .pipe(svg(config))
            .pipe(gulp.dest("assets"))
            .pipe(png());
});

##Common options

padding

Add some spacing around your sprite sheet items by setting this option

// Add 5px padding to the sprite sheet
gulp.task('sprites', function () {
    return gulp.src('assets/svg/*.svg')
            .pipe(svg({padding: 5))
            .pipe(gulp.dest("assets"))
            .pipe(png());
});

disabling previews

Disable the generation of HTML previews

gulp.task('sprites', function () {
    return gulp.src('assets/svg/*.svg')
            .pipe(svg({generatePreview: false}))
            .pipe(gulp.dest("assets"))
            .pipe(png());
});

Take a look at index.js to see which other options you can override.

Contributors

    48	Shane Osbourne
     5	thomaswelton
     3	David Mair Spiess
     1	Thomas Welton
     1	Maxime Thirouin
     1	David Blurton
     1	Alexander Flatscher

License

Copyright (c) 2014 Shane Osbourne Licensed under the MIT license.