grunt-svg-sprite

Creates an SVG sprite plus suitable CSS / Sass resources of a folder of SVG files. It is a Grunt wrapper for the svg-sprite Node.js module.

Getting Started

This plugin requires Grunt.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-svg-sprite --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-svg-sprite');

The "svgsprite" task

Overview

In your project's Gruntfile, add a section named svgsprite to the data object passed into grunt.initConfig().

grunt.initConfig({
  svgsprite: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
})

Of course, the top level options object is optional and you may define as many targets as you want. Your targets should look like this:

your_target: {
  src: ['path/to/svg/dir'],
  dest: 'path/to/css/dir'
}

As svg-sprite accepts exactly one input directory, only the first element of the src resource list will be used. Alternatively, you may simply provide a single string as src argument:

your_target: {
  src: 'path/to/svg/dir',
  dest: 'path/to/css/dir'
}

Options

You may provide both task and target specific options:

your_target: {
  src: 'path/to/svg/dir',
  dest: 'path/to/css/dir',

  // Target specific options  
  options: {
    sass: '_sprite',
    sassout: 'path/to/sass/dir'
  }
}

The options are passed to svg-sprite as configuration values. A complete reference is available here.

Usage Examples

Basic example

In this very basic example, the default options are used to create an SVG sprite along with a suitable CSS file (the css option is set to TRUE by default):

grunt.initConfig({
  svgsprite: {
    spriteCSS: {
      src: ['path/to/svg/dir'],
      dest: 'path/to/css/dir'
    }
  }
})

Sass example

In this example, custom options are used to disable CSS output and create Sass resources instead. Also, the images will be downscaled to 50 x 50 pixel (if necessary) and padded by 10 pixels before creating the SVG sprite. Finally, CSS rules specifying the image dimensions will be added and the optimized, intermediate SVG images used for creating the sprite won't be discarded.

grunt.initConfig({
  svgsprite: {
    spriteSass: {
      src: ['path/to/svg/dir'],
      dest: 'path/to/css/dir',
      options: {
        css: false,
        sass: '_sprite',
        sassout: 'path/to/sass/dir',
        maxwidth: 50,
        maxheight: 50,
        padding: 10,
        keep: true,
        dims: true
      }
    }
  }
})

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release history

v0.0.2

• Changed devDependencies & added more tests

v0.0.1

• Initial release

##Legal Copyright © 2014 Joschi Kuphal joschi@kuphal.net / @jkphl

svg-sprite is licensed under the terms of the MIT license.

The contained example SVG icons are part of the Tango Icon Library and belong to the Public Domain.