Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hiswe/gulp-svg-symbols
Convert svg files to symbols
https://github.com/hiswe/gulp-svg-symbols
Last synced: 2 days ago
JSON representation
Convert svg files to symbols
- Host: GitHub
- URL: https://github.com/hiswe/gulp-svg-symbols
- Owner: Hiswe
- License: mit
- Created: 2014-06-13T03:10:09.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T18:21:58.000Z (almost 2 years ago)
- Last Synced: 2024-12-26T17:36:27.332Z (2 days ago)
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/gulp-svg-symbols
- Size: 3.09 MB
- Stars: 169
- Watchers: 5
- Forks: 18
- Open Issues: 35
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# gulp-svg-symbols
[](https://badge.fury.io/js/gulp-svg-symbols) [](https://travis-ci.org/Hiswe/gulp-svg-symbols)
_gulp-svg-symbols_ is a minimal plugin for [gulp](http://gulpjs.com).
It converts a bunch of svg files to a single svg file containing each one as a symbol.
See [css-trick](http://css-tricks.com/svg-symbol-good-choice-icons/) for more details.
- [Install](#install)
- [Example](#example)
- [Options](#options)
- [Basics](#basics)
- [id and class](#id-and-class)
- [fontSize](#fontsize)
- [title](#title)
- [svgAttrs](#svgattrs)
- [slug](#slug)
- [templates](#templates)
- [CSS generation](#css-generation)
- [warn](#warn)
- [Advanced](#advanced)
- [templates](#templates-1)
- [transformData](#transformdata)
- [Other observations](#other-observations)
- [Other stuff](#other-stuff)
- [Rendering caveats](#rendering-caveats)
- [Migrating](#migrating)
- [More examples](#more-examples)
- [Usefull frontend lib](#usefull-frontend-lib)
- [Thanks](#thanks)
- [Credits](#credits)
- [Alternatives](#alternatives)
## Install
```
npm install --save-dev gulp-svg-symbols
```
## Example
In your gulpfile.js:
```js
const gulp = require('gulp')
const 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](http://css-tricks.com/svg-sprites-use-better-icon-fonts/)
then:
```html
```
- **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](https://github.com/Hiswe/gulp-svg-symbols/blob/master/lib/default-config.js) by passing an object as an argument to `svgSymbols()`
### Basics
#### id and class
**type:** `function` or `string`
**default:** `'%f'` and `'.%f'`
Text templates for generating symbols id & icon class
`%f` is the [speakingurled](https://www.npmjs.com/package/speakingurl) file name placeholder.
See more about the name in the [slug option](#slug)
#### fontSize
**type:** `number`
**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
**type:** `boolean` or `function` or `string`
**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](https://github.com/Hiswe/gulp-svg-symbols#id--classname)):
```js
title: `%f icon`
```
#### svgAttrs
**type:** `object`
**default:** `{class: null, xmlns: 'http://www.w3.org/2000/svg'}`
Specify attributes for the `` container tag in the default SVG template.
```js
{
class: `svg-icon-lib`,
'aria-hidden': `true`,
style: `position: absolute;`,
'data-enabled': true,
}
```
output:
```html
```
_notes:_
- this is how you can add a `class` to the generated SVG
- any string or numeric attribute will be rendered
- boolean attributes will just toggle the attribute without any value. If you need to render the boolean as a value just pass it as a string
- the attribute `xmlns:xlink="http://www.w3.org/1999/xlink"` will be added automatically if any `xlink:` is found in the SVG content
#### slug
**type:** `object` or `function`
**default:** `{}`
In order to have nice ids in the template and to keep the gulp task quite simple, gulp-svg-symbols use [speakingurl](https://www.npmjs.com/package/speakingurl).
You can pass a [speakingurl's config](https://www.npmjs.com/package/speakingurl#getsluginput-options) here:
```js
gulp.src(`*.svg`).pipe(
svgSymbols({
slug: {
separator: `_`,
},
})
)
```
You can also provide a custom function which should return a `string`:
```js
gulp.src(`*.svg`).pipe(
svgSymbols({
slug: function(name) {
return name.replace(/\s/g, `-`)
},
})
)
```
Or if you want to use [gulp-rename](https://www.npmjs.com/package/gulp-rename):
```js
gulp
.src(`*.svg`)
.pipe(rename(/* gulp rename options*/))
.pipe(
svgSymbols({
slug: name => name,
})
)
```
#### templates
**type:** `array of string`
**default:** `['default-svg', 'default-css']`
_gulp-svg-symbols_ comes with some default templates.
You can control which file are generated by specifying only the templates to keep:
```js
templates: [`default-svg`]
```
will output **only** the SVG file.
Here is the list of all provided templates:
- [**default-svg**](https://github.com/Hiswe/gulp-svg-symbols/blob/master/TEMPLATES.md#default-svg): the bundle of SVG
- [**default-css**](https://github.com/Hiswe/gulp-svg-symbols/blob/master/TEMPLATES.md#default-css): a CSS file gathering all sizes and additional styles
- [**default-demo**](https://github.com/Hiswe/gulp-svg-symbols/blob/master/TEMPLATES.md#default-demo): a demo page which provide an overview of every symbols + a way to copy/paste easily the symbol SVG code
- [**default-vue**](https://github.com/Hiswe/gulp-svg-symbols/blob/master/TEMPLATES.md#default-vue): a vue component
- [**default-css-var**](https://github.com/Hiswe/gulp-svg-symbols/blob/master/TEMPLATES.md#default-css-var): same as the CSS, but all sizes will be also declared as CSS Custom Properties
- [**default-scss**](https://github.com/Hiswe/gulp-svg-symbols/blob/master/TEMPLATES.md#default-scss): same as the CSS, but sizes will be declared as SCSS variables
- [**default-stylus**](https://github.com/Hiswe/gulp-svg-symbols/blob/master/TEMPLATES.md#default-stylus): same as the CSS, but sizes will be declared as Stylus variables
More details about the build-in templates can be found in the [TEMPLATES.md](https://github.com/Hiswe/gulp-svg-symbols/blob/master/TEMPLATES.md) file
##### CSS generation
You can deactivate CSS output by removing the CSS template from the template array.
See [templates option](https://github.com/Hiswe/gulp-svg-symbols#templates) for more details.
#### warn
**default:** `true`
Disable plugin warn messages (like: missing viewBox & depreciation warnings).
### Advanced
#### templates
Specify your own templates by providing an absolute path:
```js
templates: [
path.join(__dirname, `path/to/my/template.less`),
path.join(__dirname, `path/to/another/template.js`),
// You can still access to default templates by providing:
`default-svg`,
`default-css`,
`default-demo`,
]
```
- template engine is [lodash](http://lodash.com/docs#template).
- the output files will have the same name & extension as your files.
- every template will have acces to those datas:
```js
{
svgAttrs: {/* the same object you can pass in configuration */ },
defs: `string`,
icons: [{
id: `string`,
class: `.string`,
width: `a number as a string with a unit`,
height: `a number as a string with a unit`,
style: `string if exists`,
svg: {
name: `string (svg filename without extension)`,
id: `string`,
width: `number`,
height: `number`,
content: `the svg markup as a string`,
viewBox: `string`,
originalAttributes: {
/* every attributes before processing them */
},
},
}, {/*…*/}, ],
}
```
- and also 2 helpers functions
- `attributesToString( object )` render an object as a string of attributes
- `svgdataToSymbol( iconData )` render an icon data object to a stringed symbol
#### transformData
With the ability to provide custom templates, you also have the ability to configure custom data.
```js
transformData: function(svg, defaultData, options) {
/******
svg is same object as the one passed to the templates (see above)
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,
class: defaultData.class,
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](https://www.npmjs.com/package/gulp-cheerio)
- If you want to optimize your icons files or the SVG output, use [gulp-svgmin](https://www.npmjs.org/package/gulp-svgmin) (using SVGO)
- If you want to change the generated files name, again use [gulp-rename](https://www.npmjs.org/package/gulp-rename)
- If you want different destination for the files, use [gulp-if](https://www.npmjs.org/package/gulp-if)
- Unlike [gulp-svg-sprites](https://www.npmjs.org/package/gulp-svg-sprites) there is no way to add padding to SVG files.
If you want to include the SVG symbols directly in the DOM (i.e. no external reference) and mask it, a secure way of hiding it could be achieved in this way:
```css
.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…)
## Other stuff
### Rendering caveats
SVG can have rendering issues if:
- multiple `` have the same ids.
Use [gulp-svgmin](https://github.com/ben-eb/gulp-svgmin#per-file-options) to fix that.
- `` and `` aren't staying inside `` tags.
Move those tags **inside** the `` tags. Manually or programmatically (easy to do with [gulp-cheerio](https://www.npmjs.com/package/gulp-cheerio))
An example has been made to show all those issues resolved inside the [svgContainingIdenticalId](https://github.com/Hiswe/gulp-svg-symbols/blob/master/examples/gulpfile.js#L198-L282).
`npm run svg-containing-identical-id` to test.
### Migrating
See [MIGRATING.md](https://github.com/Hiswe/gulp-svg-symbols/blob/master/MIGRATING.md)
### More examples
Go in the [examples folder](https://github.com/Hiswe/gulp-svg-symbols/blob/master/examples), then `npm install && npm run list`.
You will have a list of all task examples there
### Usefull frontend lib
- [svg4everybody](https://www.npmjs.com/package/svg4everybody) leverage external SVG for browser which doesn't support it
### Thanks
- [Florens Verschelde](https://github.com/fvsch) for the usefull insights and PR
### Credits
- [Chris Coyier](http://css-tricks.com/) for the [trick](http://css-tricks.com/svg-symbol-good-choice-icons/)
- [Shaky Shane](https://www.npmjs.org/~shakyshane) for the [gulp-svg-sprites](https://www.npmjs.org/package/gulp-svg-sprites) plugin
- [FWeinb](https://github.com/FWeinb) for the [grunt-svgstore](https://github.com/FWeinb/grunt-svgstore) plugin
### Alternatives
- [gulp-svg-sprite](https://www.npmjs.com/package/gulp-svg-sprite)
- [gulp-svg-store](https://www.npmjs.com/package/gulp-svgstore)
- [gulp-svg-sprites](https://www.npmjs.org/package/gulp-svg-sprites)