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
npm install --save-dev gulp-svg-symbols
Example
In your gulpfile.js:
var gulp = ;var svgSymbols = ; gulp;
In your HTML, you first have to reference the SVG
then:
- 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:
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:
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
You can also provide a custom function which should return a string
:
gulp
Or if you want to use gulp-rename:
gulp
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 path // 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.
{ /****** 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: defaultDataid className: defaultDataclassName width: svgwidth + 'em' height: svgheight + '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)