Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/FWeinb/grunt-svgstore
Merge svgs from a folder
https://github.com/FWeinb/grunt-svgstore
Last synced: about 2 months ago
JSON representation
Merge svgs from a folder
- Host: GitHub
- URL: https://github.com/FWeinb/grunt-svgstore
- Owner: FWeinb
- License: mit
- Created: 2014-03-04T17:43:46.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2019-06-27T20:49:42.000Z (about 5 years ago)
- Last Synced: 2024-07-12T10:28:12.016Z (2 months ago)
- Language: JavaScript
- Homepage:
- Size: 226 KB
- Stars: 921
- Watchers: 28
- Forks: 94
- Open Issues: 33
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE-MIT
Awesome Lists containing this project
README
# grunt-svgstore [](http://badge.fury.io/js/grunt-svgstore) [](https://travis-ci.org/FWeinb/grunt-svgstore)
> Merge SVGs from a folder.
## Want to help?
I am looking for a maintainer who would like to take over this plugin.
## Why?
Because [Chris Coyier](http://shoptalkshow.com/episodes/103-louis-lazaris/#t=33:52) asked.
## Getting Started
This plugin requires Grunt `~0.4.5`
If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
```shell
npm install grunt-svgstore --save-dev
```
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
```js
grunt.loadNpmTasks('grunt-svgstore');
```
## Screencast
Chris made a screencast, using `grunt-svgstore` in a real project, you can find it [here](http://css-tricks.com/video-screencasts/screencast-134-tour-site-progress-built-jekyll-grunt-sass-svg-system/).
## The "svgstore" task
### Overview
In your project's Gruntfile, add a section named `svgstore` to the data object passed into `grunt.initConfig()`.
```js
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.
```js
{
viewBox: '0 0 100 100'
}
```
will result in:
```svg
[...]
```
#### options.symbol (since 0.2.4)
Type: `Object`
Default value: `{}`
Just like `options.svg` but will add attributes to each generated ``.
#### 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](https://github.com/einars/js-beautify#options) like: `{indent_size : 2}`, which in context looks like:
```js
default: {
options: {
formatting : {
indent_size : 2
}
}
```
See [js-beautify](https://github.com/einars/js-beautify) for more options.
#### options.includedemo (since 0.3.5)
Type: `boolean|string|function`
Default value: `false`
This will include a demo HTML (named like `destName + -demo.html`) from where you can copy your `` blocks.
The default template used looks like:
```html
svg{
width:50px;
height:50px;
fill:black !important;
}
{{{svg}}}
{{#each icons}}
{{/each}}
```
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:
```js
{
svg : '[raw HTML of the generated svg]',
icons : [
name : 'name of an item',
title : 'extracted title or name'
]
}
```
#### options.cleanup (since 0.2.6)
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.
#### options.cleanupdefs (since 0.3.0)
Type: `boolean`
Default value: `false`
When set to false, no cleanup is performed on the `` element.
#### options.inheritviewbox (since 0.4.0)
Type: `boolean`
Default value: `false`
By default, each generated `` 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 ``
`viewBox` will be derived using those values instead.
For example, with `inheritviewbox: true`,
```svg
```
will result in:
```svg
```
#### options.convertNameToId (since 0.4.0)
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:
```js
function(name) {
var dotPos = name.indexOf('.');
if ( dotPos > -1){
name = name.substring(0, dotPos);
}
return name;
}
```
#### options.fixedSizeVersion (Since 0.4.0)
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 ``.
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:
```js
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.
### Usage Examples
This example will merge all elements from the `svgs` folder into the ``-Block of the `dest.svg`. You can use that SVG in HTML like:
```html
[...]
````
```js
grunt.initConfig({
svgstore: {
options: {},
default : {
files: {
'dest/dest.svg': ['svgs/*.svg'],
},
},
},
});
```
#### options.includeTitleElement (since 0.5.0)
Type: `Boolean`
Default value: `true`
Include a `` element for screen readers. Uses the filename if no `` was found on the source SVG. Set to `false` only if you are providing your own accessible name in your code.
#### options.preserveDescElement (since 0.5.0)
Type: `Boolean`
Default value: `true`
Preserve `` element for screen readers if present. Set to `false` to suppress.
#### options.removeWithId
Type: `String`
Default value: `null`
Use this option to provide an ID of an SVG element you'd like removed. Likely use case is a bounding box path. Simply add `id='remove-me'` and then supply `removeWithId: 'remove-me'` in the options.
## Supplemental Features
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 just `stroke` in the resulting SVG. This happens whether or not you ask for that attribute to be *cleaned* via `cleanup`.
* Using the value of `currentColor` on any property with the key `fill`, will result in that property remaining in the resulting SVG (regardless of whether or not you ask for `fill` to be *cleaned* via `cleanup`). This can be used to achieve *accent color* for you SVG instances by defining the font color on a parent element via the CSS `color` property.
## 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](http://gruntjs.com/).