Merge SVGs from a folder.
Because Chris Coyier asked.
This plugin requires Grunt ~0.4.5
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-svgstore --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-svgstore');
Chris made a screencast, using grunt-svgstore
in a real project, you can find it here.
In your project's Gruntfile, add a section named svgstore
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
svgstore: {
options: {
prefix : 'icon-', // This will prefix each ID
svg: { // will add and overide the the default xmlns="http://www.w3.org/2000/svg" attribute to the resulting SVG
viewBox : '0 0 100 100',
xmlns: 'http://www.w3.org/2000/svg'
}
},
your_target: {
// Target-specific file lists and/or options go here.
},
},
});
Type: String
Default value: ''
A string value that is used to prefix each filename to generate the id.
Type: Object
Default value: {}
An object that is used to generate attributes for the resulting svg
file.
{
viewBox: '0 0 100 100'
}
will result in:
<svg viewBox="0 0 100 100">
[...]
Type: Object
Default value: {}
Just like options.svg
but will add attributes to each generated <symbol>
.
Type: Object
or boolean
Default value: false
Formatting options for generated code.
To format the generated HTML, set formatting
with options like: {indent_size : 2}
, which in context looks like:
default: {
options: {
formatting : {
indent_size : 2
}
}
See js-beautify for more options.
Type: boolean|string|function
Default value: false
This will include a demo HTML (named like destName + -demo.html
) from where you can copy your <use>
blocks.
The default template used looks like:
<!doctype html>
<html>
<head>
<style>
svg{
width:50px;
height:50px;
fill:black !important;
}
</style>
<head>
<body>
{{{svg}}}
{{#each icons}}
<svg>
<use xlink:href="#{{name}}" />
</svg>
{{/each}}
</body>
</html>
Since 0.3.5
you can customise this by passing in a string
that will be compiled via handlebars
and used as a tempalte. If it is a function this function is expected to take one parameter and return a string.
The data passed to the template looks like this:
{
svg : '[raw HTML of the generated svg]',
icons : [
name : 'name of an item',
title : 'extracted title or name'
]
}
Type: boolean
or Array
Default value: false
This option can be used to clean up inline definitions that may jeopardise later CSS-based styles.
When set to true clean up all inline style
attributes.
Apart from true / false, the value of this property can be an array of inline attributes ( like fill
, stroke
, ...) you want to remove from the elements in the SVG.
Type: boolean
Default value: false
When set to false, no cleanup is performed on the <defs>
element.
Type: boolean
Default value: false
By default, each generated <symbol>
will only automatically have a viewBox
attribute set if the original source SVG file for that symbol has a viewBox
.
When inheritviewbox
is set to true
, if the source SVG has no viewBox
but
it does have a pixel-based width
and height
, then the <symbol>
viewBox
will be derived using those values instead.
For example, with inheritviewbox: true
,
<svg width="256" height="128">
will result in:
<symbol viewBox="0 0 256 128" ...>
Type: function
The function used to generate the ID from the file name. The function receives the file name without the .svg
extension as its only argument.
The default implementation:
function(name) {
var dotPos = name.indexOf('.');
if ( dotPos > -1){
name = name.substring(0, dotPos);
}
return name;
}
Type: Object
or boolean
Default value: false
When true
or a configuration object is passed for each of the symbols another one, with suffixed id generated.
All those additional symbols have the common dimensions and refers to the original symbols with <use>
.
Original symbols are placed exactly in the middle of the fixed-size viewBox of the fixed size version.
Configuration reference and default values if true
is passed:
grunt.initConfig({
svgstore: {
options: {
fixedSizeVersion: {
width: 50,
height: 50,
suffix: '-fixed-size',
maxDigits: {
translation: 4,
scale: 4,
},
},
},
},
});
Any of the configuration object properties may be omitted.
This example will merge all elements from the svgs
folder into the <defs>
-Block of the dest.svg
. You can use that SVG in HTML like:
<!-- Include dest.svg -->
[...]
<svg><use xlink:href="#filename" /></svg>
grunt.initConfig({
svgstore: {
options: {},
default : {
files: {
'dest/dest.svg': ['svgs/*.svg'],
},
},
},
});
Type: Boolean
Default value: true
Include a <title>
element for screen readers. Uses the filename if no <title>
was found on the source SVG. Set to false
only if you are providing your own accessible name in your code.
Type: Boolean
Default value: true
Preserve <desc>
element for screen readers if present. Set to false
to suppress.
There are some hidden features available in grunt-svgstore:
- Use the
preserve--
prefix (in the source SVG), for any attributes that should be forced to remain in the resulting SVG. For example,preserve--stroke
would result in juststroke
in the resulting SVG. This happens whether or not you ask for that attribute to be cleaned viacleanup
. - Using the value of
currentColor
on any property with the keyfill
, will result in that property remaining in the resulting SVG (regardless of whether or not you ask forfill
to be cleaned viacleanup
). This can be used to achieve accent color for you SVG instances by defining the font color on a parent element via the CSScolor
property.
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.
- Added the
includeTitleElement
andpreserveDescElement
options for more control of the accessible names for icons (See #83) - Added the
externalDefs
option to include a custom set of shared<defs>
(like gradients) across multiple svgs. (See #81)
- Introducing the
preserve--
prefix for attributes to force these attributes in the result svg (See #71)
- Generate fixed sized reference based copies of symbols (See #58)
- Add a way to inherit the viewbox form the source svg (See #66)
- Expose
convertNameToId
option to customize how ids are derived from file names. (See #68) - Changed the way ids are generated by using the result of
convertNameToId
to prefix each id. (See #50)
- Preserve currentColor in
fill
attribute even ifcleanup
is set totrue
. (See #63)
- Add the ability to use
handlebars
templates inoptions.includedemo
.
- Fixed an issue with SMIL animations inside a svg symbole (See #56)
- Update to cheerio
0.17.0
- Fix broken id references between nested
<symbol>
tags. (See #50)
- Move
linearGradient
,radialGradient
andpattern
elements out of the<symbol>
tag. (See #49)
- Fix removal of unreferenced IDs (See #46)
- Changed the way ID are collected;
unreferenced IDs are removed now in order to save space.(#40) - Changed the behavior of the 'cleanup'-option (introduced in 0.2.6). Apart from true / false, the value of this property can now be an array of attributes. All attributes in the array are removed from all elements in the SVG. (#41)
- Added an option 'cleanupdefs' (default: false). When set to false, no cleanup is performed on the
<defs>
element. (#41) - Empty
<g>
elements are removed since they have no effect in a document. (#42)
Thanks to Frank3K for the PRs
- Don't generate IDs that start with a number by prefixing them with
svgstore
. (Thanks to #38)
- Add
options.clean
to remove inline styles from source svgs. (Thanks to ain) - Reformat source to use 2 spaces for indentation (Fix #36)
- To generate the id from the filename is now used as a title. (Fix #33)
- Added
options.symbol
to add attributes to generated<symbol>
s (#30) - To generate the id from the filename the name is now cut right before the first dot.
name.min.svg
becomesname
. (Fixes #29)
- Fixed lower case
viewBox
in outputted svg (fix #26)
- Fixed a bug where self-closing elements where nested.
- Move
<symbol>
-tag out of<defs>
-tag (see the spec) - Only create
<defs>
-tag if needed (e.g.<linearGradient>
is used)
- Use a
<symbol>
-tag for representing icons (See TxHawks Comment.) - Write the
viewBox
attribute to the<symbol>
-tag, - Include
title
anddesc
elements in the generated svg for each<symbol>
- use 'filename' as a fallback for
title
- Fix issue #1
- Fixed issue with referencing ids with
url()
(fix #12)
- Added
options.formatting
to format svg via js-beautify
- Fixed npm dependencies
- Inital release