gulp-svg-sprites

    4.1.2 • Public • Published

    gulp-svg-sprites Build Status

    Table of contents

    Install

    Install it locally to your project.

    $ npm install --save-dev gulp-svg-sprites

    Windows note: Using Version < 4.0.0, make sure you also have all prerequisites for node-gyp.

    Usage

    With no configuration, gulp-svg-sprites will create the following files:

    1. svg/sprite.svg - Sprite Sheet containing all of your SVGs
    2. sprite.html - A preview page with instructions & snippets
    3. 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 and 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 and 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

    You can also 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"));
    });

    Using 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 - check out 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 and 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 and 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 transformations that this library applies - so use with caution. (If you want to modify the data as well 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.

    Options

    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 icon will be used as the common class. You can also choose your own.

    selector String %f

    Easily add prefixes/suffixes to the generated CSS classnames. The %f will be replaced by the filename.

    layout String vertical

    Define the layout of the items in the sprite. Can be either "vertical", "horizontal" or "diagonal".

    svgId String %f

    In symbols or defs mode, you'll probably want to override the ID on each element. The filename will be used as a default, but can be overridden.

    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 svg option for that.

    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

    License

    Copyright (c) 2017 Shane Osbourne

    Licensed under the MIT license.

      Oh noes! Something went wrong.

      Illustration of wombats

      The package file size seems to be too large or the last published date is too old.

      We may support exploring this package in the future. Check back soon.

      Install

      npm i gulp-svg-sprites

      DownloadsWeekly Downloads

      2,219

      Version

      4.1.2

      License

      none

      Last publish

      Collaborators

      • shakyshane
      • soenkekluth