gulp-svg-symbols

gulp-svg-symbols is a minimal plugin for gulp.
It converts a bunch of svg files to a single svg file containing each one as a symbol.
See css-trick for more details.

• Install
• Example
• Options
  • Basics
    • id and className
    • fontSize
    • title
    • svgClassname
    • slug
    • templates
    • warn
  • Advanced
    • templates
    • transformData
  • Other observations
• Other stuff
  • Migrating
  • More examples
  • Usefull frontend lib
  • Credits
  • Alternatives

Install

npm install --save-dev gulp-svg-symbols

Example

In your gulpfile.js:

var gulp       = require('gulp');
var svgSymbols = require('gulp-svg-symbols');

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

In your HTML, you first have to reference the SVG
then:

<svg role="img" class="github">
  <use xlink:href="#github"></use>
</svg>

• class is the one generated in the CSS file
• xlink:href is the symbol id in the SVG file

Options

You can override the default options by passing an object as an argument to svgSymbols()

Basics

id and className

default: '%f' and '.%f'

Text templates for generating icon class & symbols id
%f is the speakingurled file name placeholder.
See more about the name in the slug option

fontSize

default: 0

This option lets you define a base font.
If it's superior to 0, then the sizes in your CSS file will be in em else sizes are provided with px.

title

default: false

Specify whether or not you want to add a missing title tag in your SVG symbols.
It should be better for accessibility.
It takes a text template (like for id/classname):

title: '%f icon'

svgClassname

default: false

Specify a class for the <svg> container tag in the default SVG template.

svgClassname: 'svg-icon-lib',

output:

<svg xmlns="http://www.w3.org/2000/svg" class="svg-icon-lib">

This is usefull when you want to include the SVG symbols directly in the DOM (i.e. no external reference)

A secure way of hiding the svg is by styling it this way:

.svg-icon-lib {
  border: 0 !important;
  clip: rect(0 0 0 0) !important;
  height: 1px !important;
  margin: -1px !important;
  overflow: hidden !important;
  padding: 0 !important;
  position: absolute !important;
  width: 1px !important;
}

A simple display: none will mess with defs rendering (gradients and so on…)

slug

default: {}

In order to have nice ids in the template and to keep the gulp task quite simple, gulp-svg-symbols use speakingurl.

You can pass a speakingurl's config here:

gulp.src('*.svg')
.pipe(svgSymbols({
  slug: {
    separator: '_',
  },
}))

You can also provide a custom function which should return a string:

gulp.src('*.svg')
.pipe(svgSymbols({
  slug: function (name) {
    return name.replace(/\s/g, '-');
  },
}))

Or if you want to use gulp-rename:

gulp.src('*.svg')
.pipe(rename(/* gulp rename options*/))
.pipe(svgSymbols({
  slug: function (name) { return name; },
}))

templates

default: ['default-svg', 'default-css']

gulp-svg-symbols come with some default templates.
Their names are:

default-svg: responsible of generating the bundled SVG file
default-css: responsible of generating the CSS file containing the symbols sizes and the CSS rules coming from your SVG files
default-demo: the demo page with the snippets you can copy & paste in your HTML

You can control which file are generated by specifying only the templates to keep:

templates: ['default-svg']

will output only the SVG file.

css generation

You can deactivate CSS output by removing the CSS template from the template array.
See templates option for more details.

warn

default: true

Disable plugin warn messages (like: missing viewBox).

Advanced

templates

Specify your own templates by providing an absolute path:

templates: [
  path.join(__dirname, 'path/to/my/template.stylus'),
  path.join(__dirname, 'path/to/another/template.html'),
  // You can still access to default templates by providing:
  'default-svg',
  'default-css',
  'default-demo'
]

• template engine is lodash.
• all svg files info are stored in the icons array and passed to every templates.
• the output files will have the same name & extension as your files.

transformData

With the ability to provide custom templates, you also have the ability to configure custom data.

transformData: function(svg, defaultData, options) {
  /******
  svg is the object containing :
    content (svg markup)
    width   (in numeric — no units)
    height  (in numeric — no units)
    viewBox (as a string)
    name    (svg filename without extension)
    originalAttributes (object of what was gathered from svg tag)

  defaultData are the ones needed by default templates
  see /lib/get-default-data.js

  options are the one you have set in your gulpfile,
    minus templates & transformData
  *******/

  return {
    // Return every datas you need
    id:         defaultData.id,
    className:  defaultData.className,
    width:      svg.width + 'em',
    height:     svg.height + 'em'
  };
}

In your templates, svg original data are accessible in icon.svg.
Of course default templates need defaultData.

Other observations

• If you want to manipulate your icons files, use gulp-cheerio
• If you want to optimize your icons files or the SVG output, use gulp-svgmin (using SVGO)
• If you want to change the generated files name, again use gulp-rename
• If you want different destination for the files, use gulp-if
• Unlike gulp-svg-sprites there is no way to add padding to svg files.

Other stuff

Migrating

See MIGRATING.md

More examples

Go in the examples folder, then npm install && gulp.
You will have a list of all task examples there

Usefull frontend lib

• svg4everybody leverage external SVG for browser which doesn't support it

Credits

• Chris Coyier for the trick
• Shaky Shane for the gulp-svg-sprites plugin
• FWeinb for the grunt-svgstore plugin

Alternatives

• gulp-svg-sprite
• gulp-svg-store
• gulp-svg-sprites (not actively maintained)