{"id":19460418,"url":"https://github.com/haensl/gulp-embed-svg","last_synced_at":"2025-06-27T10:07:52.823Z","repository":{"id":26870428,"uuid":"111341850","full_name":"haensl/gulp-embed-svg","owner":"haensl","description":"Gulp plugin to inline/embed SVG images into html files.","archived":false,"fork":false,"pushed_at":"2024-10-18T23:20:35.000Z","size":334,"stargazers_count":7,"open_issues_count":2,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-27T10:07:47.150Z","etag":null,"topics":["embed","embed-svg-images","embedding","gulp","gulp-plugins","gulpplugin","svg","svg-files","svg-images","svg-source"],"latest_commit_sha":null,"homepage":null,"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/haensl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["haensl"]}},"created_at":"2017-11-19T23:50:18.000Z","updated_at":"2024-10-18T23:19:08.000Z","dependencies_parsed_at":"2024-06-18T22:58:44.765Z","dependency_job_id":"8c8cc6bd-515e-4a10-91b1-51a4ed8b3254","html_url":"https://github.com/haensl/gulp-embed-svg","commit_stats":{"total_commits":45,"total_committers":6,"mean_commits":7.5,"dds":0.5777777777777777,"last_synced_commit":"6e9c314521bcda817afb937605a2148d19c06299"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/haensl/gulp-embed-svg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haensl%2Fgulp-embed-svg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haensl%2Fgulp-embed-svg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haensl%2Fgulp-embed-svg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haensl%2Fgulp-embed-svg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haensl","download_url":"https://codeload.github.com/haensl/gulp-embed-svg/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haensl%2Fgulp-embed-svg/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262235783,"owners_count":23279567,"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":["embed","embed-svg-images","embedding","gulp","gulp-plugins","gulpplugin","svg","svg-files","svg-images","svg-source"],"created_at":"2024-11-10T17:37:07.012Z","updated_at":"2025-06-27T10:07:52.796Z","avatar_url":"https://github.com/haensl.png","language":"JavaScript","funding_links":["https://github.com/sponsors/haensl"],"categories":[],"sub_categories":[],"readme":"# gulp-embed-svg\n\n[![NPM](https://nodei.co/npm/gulp-embed-svg.png?downloads=true)](https://nodei.co/npm/gulp-embed-svg/)\n\n[![npm version](https://badge.fury.io/js/gulp-embed-svg.svg)](http://badge.fury.io/js/gulp-embed-svg)\n[![CircleCI](https://circleci.com/gh/haensl/gulp-embed-svg.svg?style=svg)](https://circleci.com/gh/haensl/gulp-embed-svg)\n\nGulp plugin to inline/embed SVG images into html files.\n\n## Features\n\n* Inline/embed any images with an SVG source attribute (i.e. `\u003cimg src=\"some.svg\"\u003e`) and `\u003csvg\u003e` tags with a `src` attribute (i.e. `\u003csvg src=\"some.svg\"\u003e`).\n\n* Preserves all/select attributes via RegEx.\n\n* Optionally create a spritesheet from the inlined SVGs.\n\n## Installation\n\n```shell\nnpm i --save-dev gulp-embed-svg\n```\n\n## Quick Start\n\n```javascript\nconst embedSvg = require('gulp-embed-svg');\n\ngulp.task('embedSvgs', () =\u003e\n  gulp.src('*.html')\n    .pipe(embedSvg())\n    .pipe(gulp.dest('dist/')));\n```\n\nThis gulp task will inline/embed any images with an SVG source attribute (i.e. `\u003cimg src=\"some.svg\"\u003e`) and `\u003csvg\u003e` tags with a `src` attribute.\n\n## Options\n\n* [`attrs`](#attrs): Provide a regular expression to transfer select attributes from matched tags to embedded `\u003csvg\u003e`s.\n* [`createSpritesheet`](#create-spritesheet): Set to `true` to embed SVGs via a spritesheet. This reduces generated HTML filesize if you use the same SVG several times on a page.\n* [`decodeEntities`](#decode-entities): Set to `true` to decode HTML entities within the document.\n* [`root`](#root): Provide the root folder where SVG source images are located.\n* [`selectors`](#selectors): Provide custom CSS selectors to specify which tags should be replaced by embedded SVGs.\n* [`spriteIdFn`](#sprite-id-fn): Customize the `id` assigned to the sprites by providing a function that resolves path and index to a string.\n* [`spritesheetClass`](#spritesheet-class): Customize the CSS class assigned to the generated spritesheet.\n* [`xmlMode`](#xmlmode): Whether or not to read files in xml mode.\n\n### selectors `string | Array\u003cstring\u003e`\u003ca name=\"selectors\"\u003e\u003c/a\u003e\n\nProvide custom CSS selectors to specify which tags should be replaced by embedded SVGs.\n\n#### default: `['img[src$=\".svg\"]', 'svg[src$=\".svg\"]']`\n\nAll `\u003cimg\u003e` and `\u003csvg\u003e` tags with an svg source.\n\n#### Example: Only embed tags with a specific class\n\n**HTML layout**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg src=\"github-icon.svg\" class=\"inline-svg\"\u003e\u003c/svg\u003e\n    \u003cimg src=\"other-icon.svg\" /\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n**Gulp task**\n\n```javascript\nconst embedSvg = require('gulp-embed-svg');\n\ngulp.task('embedSvgs', () =\u003e\n  gulp.src('*.html')\n    .pipe(embedSvg({\n      selectors: '.inline-svg' // only replace tags with the class inline-svg\n    }))\n    .pipe(gulp.dest('dist/')));\n```\n\n**Output**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg class=\"inline-svg\"\u003e\u003c!-- svg markup from github-icon.svg --\u003e\u003c/svg\u003e\n    \u003cimg src=\"other-icon.svg\" /\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n\n### attrs `string | RegExp`\u003ca name=\"attrs\"\u003e\u003c/a\u003e\n\nProvide a regular expression to transfer select attributes from matched tags to embedded `\u003csvg\u003e`s.\n\n**Attention:** Attributes from matched tags take precedence over corresponding attributes in the source `.svg` file.\n\n#### default: `^(?!src).*$`\n\nTransfer/preserve any attribute **but** `src`.\n\n#### Example: Preserve/transfer specific attribute\n\n**HTML layout**\n\n```html\n\u003chtml\u003e\n\u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n\u003cbody\u003e\n  \u003c!-- ... --\u003e\n  \u003csvg src=\"github-icon.svg\" class=\"icon\"\u003e\u003c/svg\u003e\n  \u003c!-- ... --\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n**Gulp task**\n\n```javascript\nconst embedSvg = require('gulp-embed-svg');\n\ngulp.task('embedSvgs', () =\u003e\n  gulp.src('*.html')\n    .pipe(embedSvg({\n      attrs: /class/ // only transfer/preserve class attribute\n    }))\n    .pipe(gulp.dest('dist/')));\n```\n\n**Output**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg class=\"icon\"\u003e\u003c!-- svg markup from github-icon.svg --\u003e\u003c/svg\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### decodeEntities `boolean`\u003ca name=\"decode-entities\"\u003e\u003c/a\u003e\n\nSet to `true` to decode HTML entities within the document.\n\n#### default: `false`\n\n##### Example: Replace potential entities in document with html entities\n\n**HTML layout**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003c!-- ... --\u003e\n    \u003cspan\u003eFoo © bar 𝌆 baz ☃ qux\u003c/span\u003e\n    \u003csvg src=\"github-icon.svg\"\u003e\u003c/svg\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n**Gulp task**\n\n```javascript\nconst embedSvg = require('gulp-embed-svg');\n\ngulp.task('embedSvgs', () =\u003e\n  gulp.src('*.html')\n    .pipe(embedSvg({\n      decodeEntities: true\n    }))\n    .pipe(gulp.dest('dist/')));\n```\n\n**Output**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003c!-- ... --\u003e\n    \u003cspan\u003eFoo \u0026#xA9; bar \u0026#x1D306; baz \u0026#x2603; qux\u003c/span\u003e\n    \u003csvg class=\"icon\"\u003e\u003c!-- svg markup from github-icon.svg --\u003e\u003c/svg\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n\n### root `string`\u003ca name=\"root\"\u003e\u003c/a\u003e\n\nProvide the root folder where SVG source images are located.\n\n#### default: [`__dirname`](https://nodejs.org/docs/latest/api/globals.html#globals_dirname)\n\nThe folder in which the task is executed.\n\n#### Example: Alternate svg root\n\n**HTML layout**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg src=\"github-icon.svg\"\u003e\u003c/svg\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n**Folder structure**\n```bash\n  /src\n    index.html\n    gulpfile.js\n    /assets\n      github-icon.svg\n```\n\n**Gulp task**\n\n```javascript\nconst embedSvg = require('gulp-embed-svg');\n\ngulp.task('embedSvgs', () =\u003e\n  gulp.src('*.html')\n    .pipe(embedSvg({\n      root: './assets'\n    }))\n    .pipe(gulp.dest('dist/')));\n```\n\n### createSpritesheet `boolean`\u003ca name=\"create-spritesheet\"\u003e\u003c/a\u003e\n\nSet to `true` to embed SVGs via a spritesheet. This reduces generated HTML filesize if you use the same SVG several times on a page.\n\n#### default: `false`\n\n**Attention:** If your SVGs contain gradients, please make sure their respective `id` attribute values are unique among *all* gradients that are embedded on your page. The reason behind this is that, in order to support most (if not all) browsers, we need to extract gradient definitions from the SVGs and save them separately in the spritesheet. If there are duplicate gradient `id`s, the browser is having a hard time determining which one to use.\n\n#### Example: Create an svg spritesheet\n\n**HTML Layout**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg src=\"github-icon.svg\"\u003e\u003c/svg\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg src=\"github-icon.svg\"\u003e\u003c/svg\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n**Folder structure**\n\n```bash\n  /src\n    index.html\n    gulpfile.js\n    /assets\n      github-icon.svg\n```\n\n**Gulp task**\n\n```javascript\nconst embedSvg = require('gulp-embed-svg');\n\ngulp.task('embedSvgs', () =\u003e\n  gulp.src('*.html')\n    .pipe(embedSvg({\n      root: './assets',\n      createSpritesheet: true\n    }))\n    .pipe(gulp.dest('dist/')));\n```\n\n**Output**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003csvg class=\"svg-sprites\"\u003e\n      \u003csymbol id=\"svg-sprite-0\"\u003e\n        \u003c!-- source of github-icon.svg --\u003e\n      \u003c/symbol\u003e\n    \u003c/svg\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg\u003e\n      \u003cuse xlink:href=\"#svg-sprite-0\"\u003e\n    \u003c/svg\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg\u003e\n      \u003cuse xlink:href=\"#svg-sprite-0\"\u003e\n    \u003c/svg\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### spritesheetClass `string`\u003ca name=\"spritesheet-class\"\u003e\u003c/a\u003e\n\nCustomize the CSS class assigned to the generated spritesheet.\n\n#### default: `svg-sprites`\n\n#### Example: Change spritesheet class to my-sprites\n\n**HTML Layout**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg src=\"github-icon.svg\"\u003e\u003c/svg\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg src=\"github-icon.svg\"\u003e\u003c/svg\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n**Folder structure**\n\n```bash\n  /src\n    index.html\n    gulpfile.js\n    /assets\n      github-icon.svg\n```\n\n**Gulp task**\n\n```javascript\nconst embedSvg = require('gulp-embed-svg');\n\ngulp.task('embedSvgs', () =\u003e\n  gulp.src('*.html')\n    .pipe(embedSvg({\n      root: './assets',\n      createSpritesheet: true,\n      spritesheetClass: 'my-sprites'\n    }))\n    .pipe(gulp.dest('dist/')));\n```\n\n**Output**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003csvg class=\"my-sprites\"\u003e\n      \u003csymbol id=\"svg-sprite-0\"\u003e\n        \u003c!-- source of github-icon.svg --\u003e\n      \u003c/symbol\u003e\n    \u003c/svg\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg\u003e\n      \u003cuse xlink:href=\"#svg-sprite-0\"\u003e\n    \u003c/svg\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg\u003e\n      \u003cuse xlink:href=\"#svg-sprite-0\"\u003e\n    \u003c/svg\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### spriteIdFn `function` \u003ca name=\"sprite-id-fn\"\u003e\u003c/a\u003e\n\nCustomize the `id` assigned to the sprites by providing a function that resolves path and index to a string. The function receives the absolute/resolved path to the source SVG file as well as the index of the sprite within the page as parameters.\n\n#### default: ``(path, i) =\u003e `svg-sprite-${i}` ``\n\n#### Example: Use the filename as id\n\n**HTML Layout**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg src=\"github-icon.svg\"\u003e\u003c/svg\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg src=\"javascript-icon.svg\"\u003e\u003c/svg\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n**Folder structure**\n\n```bash\n  /src\n    index.html\n    gulpfile.js\n    /assets\n      github-icon.svg\n      javascript-icon.svg\n```\n\n**Gulp task**\n\n```javascript\nconst embedSvg = require('gulp-embed-svg');\nconst basename = require('path').basename;\n\ngulp.task('embedSvgs', () =\u003e\n  gulp.src('*.html')\n    .pipe(embedSvg({\n      root: './assets',\n      createSpritesheet: true,\n      spriteIdFn: (path, i) =\u003e basename(path, '.svg')\n    }))\n    .pipe(gulp.dest('dist/')));\n```\n\n**Output**\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c!-- ... --\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003csvg class=\"svg-sprites\"\u003e\n      \u003csymbol id=\"github-icon\"\u003e\n        \u003c!-- source of github-icon.svg --\u003e\n      \u003c/symbol\u003e\n      \u003csymbol id=\"javascript-icon\"\u003e\n        \u003c!-- source of javascript-icon.svg --\u003e\n      \u003c/symbol\u003e\n    \u003c/svg\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg\u003e\n      \u003cuse xlink:href=\"#github-icon\"\u003e\n    \u003c/svg\u003e\n    \u003c!-- ... --\u003e\n    \u003csvg\u003e\n      \u003cuse xlink:href=\"#javascript-icon\"\u003e\n    \u003c/svg\u003e\n    \u003c!-- ... --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### xmlMode `boolean` \u003ca name=\"xmlmode\"\u003e\u003c/a\u003e\n\nFlag to toggle [xml mode](https://github.com/fb55/htmlparser2/wiki/Parser-options#option-xmlmode).\n\n#### default: `true`\n\n## [Changelog](CHANGELOG.md)\n\n## [License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaensl%2Fgulp-embed-svg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaensl%2Fgulp-embed-svg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaensl%2Fgulp-embed-svg/lists"}