# gulp-svg-symbols

> Convert SVG files to symbols with gulp

Latest version **3.2.3** (published 2018-11-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-svg-symbols
pnpm add gulp-svg-symbols
yarn add gulp-svg-symbols
bun add gulp-svg-symbols
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.2.3 |
| Published | 2018-11-27 |
| First published | 2014-06-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 10 |
| Unpacked size | 214.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 168 |
| Author | Yannick Aïvayan |
| Maintainers | hiswe |
| Keywords | gulpplugin, svg, symbols |

## Links

- npm: https://www.npmjs.com/package/gulp-svg-symbols
- Repository: https://github.com/Hiswe/gulp-svg-symbols
- Issues: https://github.com/Hiswe/gulp-svg-symbols/issues
- npm.io page: https://npm.io/package/gulp-svg-symbols

## Dependencies (10)

- [vinyl](https://npm.io/package/vinyl.md) ^2.2.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.11
- [cheerio](https://npm.io/package/cheerio.md) ^1.0.0-rc.2
- [through2](https://npm.io/package/through2.md) ^3.0.0
- [ansi-grey](https://npm.io/package/ansi-grey.md) ^0.1.1
- [fancy-log](https://npm.io/package/fancy-log.md) ^1.3.2
- [ansi-yellow](https://npm.io/package/ansi-yellow.md) ^0.1.1
- [consolidate](https://npm.io/package/consolidate.md) ^0.15.1
- [speakingurl](https://npm.io/package/speakingurl.md) ^14.0.1
- [plugin-error](https://npm.io/package/plugin-error.md) ^1.0.1

## Recent versions

- 3.2.3 (latest) — 2018-11-27
- 3.2.0 — 2018-07-25
- 3.1.1 — 2018-05-07
- 3.1.0 — 2018-02-10
- 3.0.2 — 2018-02-08
- 3.0.1 — 2018-02-08
- 3.0.0 — 2018-01-06
- 2.0.2 — 2016-11-05
- 2.0.1 — 2016-10-27
- 2.0.0 — 2016-08-16
- 1.0.0 — 2015-09-30
- 0.3.2 — 2015-09-22
- 0.3.1 — 2014-10-03
- 0.3.0 — 2014-10-03
- 0.2.1 — 2014-09-26
- … 5 more at https://npm.io/package/gulp-svg-symbols/versions

## README

# gulp-svg-symbols

[![npm version](https://badge.fury.io/js/gulp-svg-symbols.svg)](https://badge.fury.io/js/gulp-svg-symbols) [![Build Status](https://travis-ci.org/Hiswe/gulp-svg-symbols.svg?branch=master)](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.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [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)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## 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
<svg role="img" class="github">
  <use xlink:href="#github"></use>
</svg>
```

- **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 `<svg>` container tag in the default SVG template.

```js
{
  class: `svg-icon-lib`,
  'aria-hidden': `true`,
  style: `position: absolute;`,
  'data-enabled': true,
}
```

output:

```html
<svg xmlns="http://www.w3.org/2000/svg" class="svg-icon-lib" aria-hidden="true" style="position: absolute;" data-enabled>
```

_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 `<defs>` have the same ids.  
  Use [gulp-svgmin](https://github.com/ben-eb/gulp-svgmin#per-file-options) to fix that.
- `<clipPath>` and `<mask>` aren't staying inside `<defs>` tags.  
  Move those tags **inside** the `<defs>` 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)

---
_Source: https://npm.io/package/gulp-svg-symbols · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._