Gulp plugin to embed/inline svg images and optionally create a spritesheet.
npm install gulp-embed-svg


Gulp plugin to inline/embed SVG images into html files.
* Inline/embed any images with an SVG source attribute (i.e. ) and tags with a src attribute (i.e. ).
* Preserves all/select attributes via RegEx.
* Optionally create a spritesheet from the inlined SVGs.
``shell`
npm i --save-dev gulp-embed-svg
`javascript
const embedSvg = require('gulp-embed-svg');
gulp.task('embedSvgs', () =>
gulp.src('*.html')
.pipe(embedSvg())
.pipe(gulp.dest('dist/')));
`
This gulp task will inline/embed any images with an SVG source attribute (i.e. ) and
* attrs: Provide a regular expression to transfer select attributes from matched tags to embedded
Provide custom CSS selectors to specify which tags should be replaced by embedded SVGs.
#### default: ['img[src$=".svg"]', 'svg[src$=".svg"]']
All and
#### Example: Only embed tags with a specific class
HTML layout
`html`
Gulp task
`javascript
const embedSvg = require('gulp-embed-svg');
gulp.task('embedSvgs', () =>
gulp.src('*.html')
.pipe(embedSvg({
selectors: '.inline-svg' // only replace tags with the class inline-svg
}))
.pipe(gulp.dest('dist/')));
`
Output
`html`
Provide a regular expression to transfer select attributes from matched tags to embedded
Attention: Attributes from matched tags take precedence over corresponding attributes in the source .svg file.
#### default: ^(?!src).*$
Transfer/preserve any attribute but src.
#### Example: Preserve/transfer specific attribute
HTML layout
`html`
Gulp task
`javascript
const embedSvg = require('gulp-embed-svg');
gulp.task('embedSvgs', () =>
gulp.src('*.html')
.pipe(embedSvg({
attrs: /class/ // only transfer/preserve class attribute
}))
.pipe(gulp.dest('dist/')));
`
Output
`html`
Set to true to decode HTML entities within the document.
#### default: false
##### Example: Replace potential entities in document with html entities
HTML layout
`html`
Foo © bar 𝌆 baz ☃ qux
Gulp task
`javascript
const embedSvg = require('gulp-embed-svg');
gulp.task('embedSvgs', () =>
gulp.src('*.html')
.pipe(embedSvg({
decodeEntities: true
}))
.pipe(gulp.dest('dist/')));
`
Output
`html`
Foo © bar 𝌆 baz ☃ qux
Provide the root folder where SVG source images are located.
#### default: __dirname
The folder in which the task is executed.
#### Example: Alternate svg root
HTML layout
`html`
Folder structure
`bash`
/src
index.html
gulpfile.js
/assets
github-icon.svg
Gulp task
`javascript
const embedSvg = require('gulp-embed-svg');
gulp.task('embedSvgs', () =>
gulp.src('*.html')
.pipe(embedSvg({
root: './assets'
}))
.pipe(gulp.dest('dist/')));
`
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.
#### default: false
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 ids, the browser is having a hard time determining which one to use.
#### Example: Create an svg spritesheet
HTML Layout
`html`
Folder structure
`bash`
/src
index.html
gulpfile.js
/assets
github-icon.svg
Gulp task
`javascript
const embedSvg = require('gulp-embed-svg');
gulp.task('embedSvgs', () =>
gulp.src('*.html')
.pipe(embedSvg({
root: './assets',
createSpritesheet: true
}))
.pipe(gulp.dest('dist/')));
`
Output
`html`
Customize the CSS class assigned to the generated spritesheet.
#### default: svg-sprites
#### Example: Change spritesheet class to my-sprites
HTML Layout
`html`
Folder structure
`bash`
/src
index.html
gulpfile.js
/assets
github-icon.svg
Gulp task
`javascript
const embedSvg = require('gulp-embed-svg');
gulp.task('embedSvgs', () =>
gulp.src('*.html')
.pipe(embedSvg({
root: './assets',
createSpritesheet: true,
spritesheetClass: 'my-sprites'
}))
.pipe(gulp.dest('dist/')));
`
Output
`html`
Customize 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.
#### default: (path, i) => svg-sprite-${i}
#### Example: Use the filename as id
HTML Layout
`html`
Folder structure
`bash`
/src
index.html
gulpfile.js
/assets
github-icon.svg
javascript-icon.svg
Gulp task
`javascript
const embedSvg = require('gulp-embed-svg');
const basename = require('path').basename;
gulp.task('embedSvgs', () =>
gulp.src('*.html')
.pipe(embedSvg({
root: './assets',
createSpritesheet: true,
spriteIdFn: (path, i) => basename(path, '.svg')
}))
.pipe(gulp.dest('dist/')));
`
Output
`html`
Flag to toggle xml mode.
#### default: true`