{"id":21951342,"url":"https://github.com/hiswe/gulp-svg-symbols","last_synced_at":"2025-04-05T14:09:54.153Z","repository":{"id":17861608,"uuid":"20790549","full_name":"Hiswe/gulp-svg-symbols","owner":"Hiswe","description":"Convert svg files to symbols ","archived":false,"fork":false,"pushed_at":"2023-01-03T18:21:58.000Z","size":3245,"stargazers_count":170,"open_issues_count":35,"forks_count":18,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-29T13:11:45.348Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/gulp-svg-symbols","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hiswe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-06-13T03:10:09.000Z","updated_at":"2025-01-25T23:09:29.000Z","dependencies_parsed_at":"2022-08-07T14:30:12.412Z","dependency_job_id":null,"html_url":"https://github.com/Hiswe/gulp-svg-symbols","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hiswe%2Fgulp-svg-symbols","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hiswe%2Fgulp-svg-symbols/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hiswe%2Fgulp-svg-symbols/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hiswe%2Fgulp-svg-symbols/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hiswe","download_url":"https://codeload.github.com/Hiswe/gulp-svg-symbols/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247345856,"owners_count":20924102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-29T06:13:38.363Z","updated_at":"2025-04-05T14:09:54.136Z","avatar_url":"https://github.com/Hiswe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gulp-svg-symbols\n\n[![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)\n\n_gulp-svg-symbols_ is a minimal plugin for [gulp](http://gulpjs.com).  \nIt converts a bunch of svg files to a single svg file containing each one as a symbol.  \nSee [css-trick](http://css-tricks.com/svg-symbol-good-choice-icons/) for more details.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [Install](#install)\n- [Example](#example)\n- [Options](#options)\n  - [Basics](#basics)\n    - [id and class](#id-and-class)\n    - [fontSize](#fontsize)\n    - [title](#title)\n    - [svgAttrs](#svgattrs)\n    - [slug](#slug)\n    - [templates](#templates)\n      - [CSS generation](#css-generation)\n    - [warn](#warn)\n  - [Advanced](#advanced)\n    - [templates](#templates-1)\n    - [transformData](#transformdata)\n  - [Other observations](#other-observations)\n- [Other stuff](#other-stuff)\n  - [Rendering caveats](#rendering-caveats)\n  - [Migrating](#migrating)\n  - [More examples](#more-examples)\n  - [Usefull frontend lib](#usefull-frontend-lib)\n  - [Thanks](#thanks)\n  - [Credits](#credits)\n  - [Alternatives](#alternatives)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Install\n\n```\nnpm install --save-dev gulp-svg-symbols\n```\n\n## Example\n\nIn your gulpfile.js:\n\n```js\nconst gulp = require('gulp')\nconst svgSymbols = require('gulp-svg-symbols')\n\ngulp.task(`sprites`, function() {\n  return gulp\n    .src(`assets/svg/*.svg`)\n    .pipe(svgSymbols())\n    .pipe(gulp.dest(`assets`))\n})\n```\n\nIn your HTML, you first have to [reference the SVG](http://css-tricks.com/svg-sprites-use-better-icon-fonts/)  \nthen:\n\n```html\n\u003csvg role=\"img\" class=\"github\"\u003e\n  \u003cuse xlink:href=\"#github\"\u003e\u003c/use\u003e\n\u003c/svg\u003e\n```\n\n- **class** is the one generated in the CSS file\n- **xlink:href** is the symbol id in the SVG file\n\n## Options\n\nYou 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()`\n\n### Basics\n\n#### id and class\n\n**type:** `function` or `string`  \n**default:** `'%f'` and `'.%f'`\n\nText templates for generating symbols id \u0026 icon class  \n`%f` is the [speakingurled](https://www.npmjs.com/package/speakingurl) file name placeholder.  \nSee more about the name in the [slug option](#slug)\n\n#### fontSize\n\n**type:** `number`  \n**default:** `0`\n\nThis option lets you define a base font.  \nIf it's superior to 0, then the sizes in your CSS file will be in **em** else sizes are provided with **px**.\n\n#### title\n\n**type:** `boolean` or `function` or `string`  \n**default:** `false`\n\nSpecify whether or not you want to add a missing `title` tag in your SVG symbols.  \nIt should be better for _accessibility_.  \nIt takes a text template (like for [id/classname](https://github.com/Hiswe/gulp-svg-symbols#id--classname)):\n\n```js\ntitle: `%f icon`\n```\n\n#### svgAttrs\n\n**type:** `object`  \n**default:** `{class: null, xmlns: 'http://www.w3.org/2000/svg'}`\n\nSpecify attributes for the `\u003csvg\u003e` container tag in the default SVG template.\n\n```js\n{\n  class: `svg-icon-lib`,\n  'aria-hidden': `true`,\n  style: `position: absolute;`,\n  'data-enabled': true,\n}\n```\n\noutput:\n\n```html\n\u003csvg xmlns=\"http://www.w3.org/2000/svg\" class=\"svg-icon-lib\" aria-hidden=\"true\" style=\"position: absolute;\" data-enabled\u003e\n```\n\n_notes:_\n\n- this is how you can add a `class` to the generated SVG\n- any string or numeric attribute will be rendered\n- 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\n- the attribute `xmlns:xlink=\"http://www.w3.org/1999/xlink\"` will be added automatically if any `xlink:` is found in the SVG content\n\n#### slug\n\n**type:** `object` or `function`  \n**default:** `{}`\n\nIn 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).\n\nYou can pass a [speakingurl's config](https://www.npmjs.com/package/speakingurl#getsluginput-options) here:\n\n```js\ngulp.src(`*.svg`).pipe(\n  svgSymbols({\n    slug: {\n      separator: `_`,\n    },\n  })\n)\n```\n\nYou can also provide a custom function which should return a `string`:\n\n```js\ngulp.src(`*.svg`).pipe(\n  svgSymbols({\n    slug: function(name) {\n      return name.replace(/\\s/g, `-`)\n    },\n  })\n)\n```\n\nOr if you want to use [gulp-rename](https://www.npmjs.com/package/gulp-rename):\n\n```js\ngulp\n  .src(`*.svg`)\n  .pipe(rename(/* gulp rename options*/))\n  .pipe(\n    svgSymbols({\n      slug: name =\u003e name,\n    })\n  )\n```\n\n#### templates\n\n**type:** `array of string`  \n**default:** `['default-svg', 'default-css']`\n\n_gulp-svg-symbols_ comes with some default templates.\n\nYou can control which file are generated by specifying only the templates to keep:\n\n```js\ntemplates: [`default-svg`]\n```\n\nwill output **only** the SVG file.\n\nHere is the list of all provided templates:\n\n- [**default-svg**](https://github.com/Hiswe/gulp-svg-symbols/blob/master/TEMPLATES.md#default-svg): the bundle of SVG\n- [**default-css**](https://github.com/Hiswe/gulp-svg-symbols/blob/master/TEMPLATES.md#default-css): a CSS file gathering all sizes and additional styles\n- [**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\n- [**default-vue**](https://github.com/Hiswe/gulp-svg-symbols/blob/master/TEMPLATES.md#default-vue): a vue component\n- [**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\n- [**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\n- [**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\n\nMore 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\n\n##### CSS generation\n\nYou can deactivate CSS output by removing the CSS template from the template array.  \nSee [templates option](https://github.com/Hiswe/gulp-svg-symbols#templates) for more details.\n\n#### warn\n\n**default:** `true`\n\nDisable plugin warn messages (like: missing viewBox \u0026 depreciation warnings).\n\n### Advanced\n\n#### templates\n\nSpecify your own templates by providing an absolute path:\n\n```js\ntemplates: [\n  path.join(__dirname, `path/to/my/template.less`),\n  path.join(__dirname, `path/to/another/template.js`),\n  // You can still access to default templates by providing:\n  `default-svg`,\n  `default-css`,\n  `default-demo`,\n]\n```\n\n- template engine is [lodash](http://lodash.com/docs#template).\n- the output files will have the same name \u0026 extension as your files.\n- every template will have acces to those datas:\n\n```js\n{\n  svgAttrs: {/*  the same object you can pass in configuration */ },\n  defs: `string`,\n  icons: [{\n    id: `string`,\n    class: `.string`,\n    width: `a number as a string with a unit`,\n    height: `a number as a string with a unit`,\n    style: `string if exists`,\n    svg: {\n      name: `string (svg filename without extension)`,\n      id: `string`,\n      width: `number`,\n      height: `number`,\n      content: `the svg markup as a string`,\n      viewBox: `string`,\n      originalAttributes: {\n        /* every attributes before processing them */\n      },\n    },\n  }, {/*…*/}, ],\n}\n```\n\n- and also 2 helpers functions\n  - `attributesToString( object )` render an object as a string of attributes\n  - `svgdataToSymbol( iconData )` render an icon data object to a stringed symbol\n\n#### transformData\n\nWith the ability to provide custom templates, you also have the ability to configure custom data.\n\n```js\ntransformData: function(svg, defaultData, options) {\n  /******\n  svg is same object as the one passed to the templates (see above)\n\n  defaultData are the ones needed by default templates\n  see /lib/get-default-data.js\n\n  options are the one you have set in your gulpfile,\n    minus templates \u0026 transformData\n  *******/\n\n  return {\n    // Return every datas you need\n    id:         defaultData.id,\n    class:      defaultData.class,\n    width:      `${svg.width}em`,\n    height:     `${svg.height}em`\n  };\n}\n```\n\nIn your templates, svg original data are accessible in `icon.svg`.  \nOf course default templates need `defaultData`.\n\n### Other observations\n\n- If you want to manipulate your icons files, use [gulp-cheerio](https://www.npmjs.com/package/gulp-cheerio)\n- If you want to optimize your icons files or the SVG output, use [gulp-svgmin](https://www.npmjs.org/package/gulp-svgmin) (using SVGO)\n- If you want to change the generated files name, again use [gulp-rename](https://www.npmjs.org/package/gulp-rename)\n- If you want different destination for the files, use [gulp-if](https://www.npmjs.org/package/gulp-if)\n- Unlike [gulp-svg-sprites](https://www.npmjs.org/package/gulp-svg-sprites) there is no way to add padding to SVG files.\n\nIf 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:\n\n```css\n.svg-icon-lib {\n  border: 0 !important;\n  clip: rect(0 0 0 0) !important;\n  height: 1px !important;\n  margin: -1px !important;\n  overflow: hidden !important;\n  padding: 0 !important;\n  position: absolute !important;\n  width: 1px !important;\n}\n```\n\nA simple `display: none` will mess with defs rendering (gradients and so on…)\n\n## Other stuff\n\n### Rendering caveats\n\nSVG can have rendering issues if:\n\n- multiple `\u003cdefs\u003e` have the same ids.  \n  Use [gulp-svgmin](https://github.com/ben-eb/gulp-svgmin#per-file-options) to fix that.\n- `\u003cclipPath\u003e` and `\u003cmask\u003e` aren't staying inside `\u003cdefs\u003e` tags.  \n  Move those tags **inside** the `\u003cdefs\u003e` tags. Manually or programmatically (easy to do with [gulp-cheerio](https://www.npmjs.com/package/gulp-cheerio))\n\nAn 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).\n\n`npm run svg-containing-identical-id` to test.\n\n### Migrating\n\nSee [MIGRATING.md](https://github.com/Hiswe/gulp-svg-symbols/blob/master/MIGRATING.md)\n\n### More examples\n\nGo in the [examples folder](https://github.com/Hiswe/gulp-svg-symbols/blob/master/examples), then `npm install \u0026\u0026 npm run list`.  \nYou will have a list of all task examples there\n\n### Usefull frontend lib\n\n- [svg4everybody](https://www.npmjs.com/package/svg4everybody) leverage external SVG for browser which doesn't support it\n\n### Thanks\n\n- [Florens Verschelde](https://github.com/fvsch) for the usefull insights and PR\n\n### Credits\n\n- [Chris Coyier](http://css-tricks.com/) for the [trick](http://css-tricks.com/svg-symbol-good-choice-icons/)\n- [Shaky Shane](https://www.npmjs.org/~shakyshane) for the [gulp-svg-sprites](https://www.npmjs.org/package/gulp-svg-sprites) plugin\n- [FWeinb](https://github.com/FWeinb) for the [grunt-svgstore](https://github.com/FWeinb/grunt-svgstore) plugin\n\n### Alternatives\n\n- [gulp-svg-sprite](https://www.npmjs.com/package/gulp-svg-sprite)\n- [gulp-svg-store](https://www.npmjs.com/package/gulp-svgstore)\n- [gulp-svg-sprites](https://www.npmjs.org/package/gulp-svg-sprites)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiswe%2Fgulp-svg-symbols","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhiswe%2Fgulp-svg-symbols","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiswe%2Fgulp-svg-symbols/lists"}