grunt-svgstore

grunt-svgstore

Merge SVGs from a folder.

Why?

Because Chris Coyier asked.

Getting Started

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');

Screencast

Chris made a screencast, using grunt-svgstore in a real project, you can find it here.

The "svgstore" task

Overview

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.
    },
  },
});

Options

options.prefix

Type: String
Default value: ''

A string value that is used to prefix each filename to generate the id.

options.svg

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">
[...]

options.symbol (since 0.2.4)

Type: Object
Default value: {}

Just like options.svg but will add attributes to each generated <symbol>.

options.formatting (since 0.0.4)

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.

options.includedemo (since 0.1.0)

Type: boolean
Default value: false

This will include a demo HTML (named like destName + -demo.html) from where you can copy your <use> blocks.

options.cleanup (since 0.2.6)

Type: boolean or Array Default value: false

Clean up all inline style definitions that may jeopardise later stylesheet-based colouring (fill). Apart from true / false, the value of this property can be an array of attributes. All attributes in the array are removed from all elements in the SVG.

options.cleanupdefs (since 0.3.0)

Type: boolean
Default value: false

When set to false, no cleanup is performed on the <defs> element.

Usage Examples

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'],
      },
    },
  },
});

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

0.3.4

• Fixed an issue with SMIL animations inside a svg symbole (See #56)
• Update to cheerio 0.17.0

0.3.3

• Fix broken id references between nested <symbol> tags. (See #50)

0.3.2

• Move linearGradient, radialGradient and pattern elements out of the <symbol> tag. (See #49)

0.3.1

• Fix removal of unreferenced IDs (See #46)

0.3.0

• 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

0.2.7

• Don't generate IDs that start with a number by prefixing them with svgstore. (Thanks to #38)

0.2.6

• Add options.clean to remove inline styles from source svgs. (Thanks to ain)
• Reformat source to use 2 spaces for indentation (Fix #36)

0.2.5

• To generate the id from the filename is now used as a title. (Fix #33)

0.2.4

• 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 becomes name. (Fixes #29)

0.2.3

• Fixed lower case viewBox in outputted svg (fix #26)

0.2.2

• Fixed a bug where self-closing elements where nested.

0.2.1

• Move <symbol>-tag out of <defs>-tag (see the spec)
• Only create <defs>-tag if needed (e.g. <linearGradient> is used)

0.2.0

• Use a <symbol>-tag for representing icons (See TxHawks Comment.)
• Write the viewBox attribute to the <symbol>-tag,
• Include title and desc elements in the generated svg for each <symbol>
• use 'filename' as a fallback for title
• Fix issue #1

0.1.0

• Always add xmlns namspace.
• Added the includedemo option.
• Fixed Issues #20, #19, #18

0.0.4

• Fixed issue with referencing ids with url() (fix #12)

0.0.3

• Added options.formatting to format svg via js-beautify

0.0.2

• Fixed npm dependencies

0.0.1

• Inital release

Changelog

0.3.4

• Fixed an issue with SMIL animations inside a svg symbole (See #56)
• Update to cheerio 0.17.0