Install it locally to your project.
$ npm install --save-dev gulp-svg-spritesWindows note: Using Version < 4.0.0 Make sure, you also have all prerequisities for node-gyp.
##Usage
With no configuration, gulp-svg-sprites will create the following files:
svg/sprite.svg- Sprite Sheet containing all of your SVGs.sprite.html- A preview page with instructions & snippets.css/sprite.css- A CSS file with the code needed to use the sprite.
var svgSprite = require("gulp-svg-sprites");
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite())
.pipe(gulp.dest("assets"));
});Then, if you had a facebook.svg file, you'd be able to use the following markup in your webpage:
<i class="icon facebook"></i>##PNG fallback
You can easily support old browsers by piping the new SVG sprite through to another gulp task. There will be a
no-svg class generated automatically in the CSS, so you'll just need to use something like Modernizr
to set the no-svg class on the <body> tag of your website.
var svgSprite = require("gulp-svg-sprites");
var filter = require('gulp-filter');
var svg2png = require('gulp-svg2png');
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite())
.pipe(gulp.dest("assets")) // Write the sprite-sheet + CSS + Preview
.pipe(filter("**/*.svg")) // Filter out everything except the SVG file
.pipe(svg2png()) // Create a PNG
.pipe(gulp.dest("assets"));
});##Symbols mode
Pass mode: "symbols" to output SVG data as this CSS TRICKS article outlines.
You'll get an SVG file & a preview file showing how to use it.
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite({mode: "symbols"}))
.pipe(gulp.dest("assets"));
});##Defs mode
Pass mode: "defs" to output SVG data as this CSS TRICKS article outlines.
You'll get an SVG file & a preview file showing how to use it.
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite({mode: "defs"}))
.pipe(gulp.dest("assets"));
});###Custom Selectors
By default, the filename will be used as the selector in the CSS, but this is how you'd override it (the %f will be replaced with the filename)
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite({
selector: "icon-%f"
}))
.pipe(gulp.dest("assets"));
});###Custom IDs
With the symbols or defs mode, it's probably the ID you'll want to override. No problem.
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite({
svgId: "svg-%f"
}))
.pipe(gulp.dest("assets"));
});###Custom filenames
Change the generated filenames with ease. For example, if you want to create a scss partial instead, you could just do:
// Custom CSS filename
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite({
cssFile: "scss/_sprite.scss"
}))
.pipe(gulp.dest("assets"));
});
// Custom SVG filename
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite({
svg: {
sprite: "svg.svg"
}
}))
.pipe(gulp.dest("assets"));
});
// Custom Preview filename + Custom SVG filename
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite({
svg: {
sprite: "svg.svg"
},
preview: {
sprite: "index.html"
}
}))
.pipe(gulp.dest("assets"));
});###Base Size Set the font-size of the .icon class. Just pass a plain number, no units.
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite({
baseSize: 16
}))
.pipe(gulp.dest("assets"));
});###No previews If you don't want 'em. Works in all modes.
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite({
preview: false
}))
.pipe(gulp.dest("assets"));
});###Use the built in SCSS template
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite({
templates: { scss: true }
}))
.pipe(gulp.dest("assets"));
});##Advanced: Custom Templates Templates use Lodash Templates - checkout their docs for usage instructions. Or take a look at the default css or the default scss for tips.
You can get your hands on JUST the SVG Data & provide your own templates. For example, if you want to provide your own template for the CSS output, you could do this:
var config = {
templates: {
css: require("fs").readFileSync("./path/to/your/template.css", "utf-8")
}
};
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite(config))
.pipe(gulp.dest("assets"));
});You can override all the templates used in the same way.
##Advanced: Data Transforms
If you want to do some custom stuff with your templates, you might need to transform the SVG data before it gets to your template. There
are two functions you can provide to do this & they'll override the internal ones. Override transformData and you'll have direct access
to the data returned from svg-sprite-data. This will skip the few transformation that
this library applies - so use with caution. (if you want to modify the data aswell after our internal modifications, use afterTransform instead).
// Synchronous
var config = {
transformData: function (data, config) {
return data; // modify the data and return it
},
templates: {
css: require("fs").readFileSync("./path/to/your/template.css", "utf-8")
}
};
// Asynchronous
var config = {
asyncTransforms: true,
transformData: function (data, config, done) {
done(data); // modify the data and pass it
},
templates: {
css: require("fs").readFileSync("./path/to/your/template.css", "utf-8")
}
};
gulp.task('sprites', function () {
return gulp.src('assets/svg/*.svg')
.pipe(svgSprite(config))
.pipe(gulp.dest("assets"));
});You can override all the templates used here in the same way. If you are doing any async work in these callbacks set asyncTransforms to true in the config.
| Name | Type | Default | Description |
|---|---|---|---|
| mode | String | sprite |
Define which mode to run in. Can be either "sprite", "defs" or "symbols" |
| common | String | icon |
By default, the class |
| selector | String | %f |
Easily add prefixes/suffixes to the generated CSS classnames. The |
| layout | String | vertical |
Define the layout of the items in the sprite. Can be either "vertical", "horizontal" or "diagonal" |
| svgId | String | %f |
In |
| cssFile | String | css/sprite.css |
Define the path & filename of the CSS file. Using this, you could easily create a SASS partial for example |
| svgPath | String | ../%f |
Define the path to the SVG file that be written to the CSS file. Note: this does NOT alter
the actual write-path of the SVG file. See the |
| pngPath | String | ../%f |
If you're creating a PNG fallback, define the path to it that be written to the CSS file. |
| preview | Object | Paths to preview files. |
|
| preview.sprite | String | sprite.html |
|
| preview.defs | String | defs.html |
|
| preview.symbols | String | symbols.html |
|
| svg | Object | Paths to SVG files. |
|
| svg.sprite | String | svg/sprite.svg |
|
| svg.defs | String | svg/defs.svg |
|
| svg.symbols | String | svg/symbols.svg |
|
| padding | Number | 0 |
Add padding to sprite items |
| asyncTransforms | Boolean | false |
Use async transforms |
| baseSize | Number | 10 |
Set the base font-size for the icon element |
| transformData | Function | transformData |
Override the default data transforms |
| afterTransform | Function | afterTransform |
Apply additional data transforms AFTER the defaults |