SVG Spritemap Webpack Plugin
This webpack plugin generates a single SVG spritemap containing multiple <symbol>
elements from all .svg
files in a directory. In addition, it can optimize the output and can also generate a stylesheet containing the sprites to be used directly from CSS. Chris Coyier has a good write-up about the why's and how's of this technique on CSS Tricks. Use it in combination with the svg4everybody
package to easily and correctly load SVGs from the spritemap in all browsers.
Compatibility
Version ^2.0.0
of this plugin is compatible with webpack ^4.0.0
. When using an older version of webpack, make sure to install the ^1.0.0
(svg-spritemap-webpack-plugin@^1.0.0
) release of this plugin.
Installation
npm install svg-spritemap-webpack-plugin --save-dev
Usage
Webpack configuration This plugin can be added to webpack like any other, the options are listed down below.
const SVGSpritemapPlugin = require('svg-spritemap-webpack-plugin');
module.exports = {
// ...
plugins: [
new SVGSpritemapPlugin({
// Optional options object
})
]
}
SVG element
When there's a file phone.svg
in the source directory and the prefix
option is set to sprite-
(default), the sprite can be included in a HTML-file like so:
<svg>
<use xlink:href="/path/to/spritemap.svg#sprite-phone"></use>
</svg>
Options
The SVGSpritemapPlugin()
supports multiple options passed as an object. This object can contain the following keys, the default values for these options are listed behind the option names.
src
– '**/*.svg'
Pattern (or an array of patterns) for glob
used to find the SVGs that should be in the spritemap.
filename
– 'spritemap.svg'
Filename of the generated file (located at the webpack output.path
), [hash]
and [contenthash]
are supported.
prefix
– 'sprite-'
Prefix added to sprite id
in the spritemap. It will be used for the class/spritename in the generated styles as well.
gutter
– 2
Amount of pixels added between each sprite to prevent overlap.
styles
– false
Filename for the generated styles file (CSS, SCSS, LESS). This allows for using the sprites within a CSS-file instead of through a <svg>
element in HTML. Although the latter method is preferred, situations may arise where extra HTML elements are not feasible.
The file that's generated will be placed in a different location depending on the value specified.
-
false
Disable generating the styles file. -
'filename.ext'
Add the styles file to the webpack assets, this will result in the file being written to the webpackoutput.path
,[hash]
and[contenthash]
are supported. -
'/path/to/filename.ext'
Write the styles file to a specific directory. -
'~filename.ext'
Write the styles file to the plugin directory. This allows for importing it from a JavaScript bundle or Sass very easily:// Import it from a JavaScript bundle (styles: '~sprites.css') require('svg-spritemap-webpack-plugin/sprites.css');
// Import it from Sass (styles: '~sprites.scss') @import '~svg-spritemap-webpack-plugin/sprites';
The value for the styles
option should end in a supported style extension and the generated file will have language-specific content:
-
.css
Generates a class-based stylesheet where the classnames are equal to the spritename (including prefix) containing the sprite as abackground-image
. -
.scss
/.sass
Generates a Sass map containing the spritenames (excluding prefix) as keys and the sprite as values, comes with asprite()
mixin..example { // Using the included sprite() mixin @include sprite('phone'); // Using the SVG from the map directly background-image: url(map-get($sprites, 'phone')); }
Basic support for variables using a custom syntax is available when using Sass, this feature allows developers to restyle their sprites on the fly using the
sprite()
mixin. -
.less
Generates LESS variables for each sprite based on the spritename (including prefix) with the sprite as value, comes with a.sprite()
mixin..example { // Using the included .sprite() mixin .sprite(@sprite-phone); // Using the SVG variable directly background-image: url(@sprite-phone); }
svgo
– true
Options object to pass to SVG Optimizer
. Note that the cleanupIDs
plugin will always be disabled because it's required for this kind of SVG spritemap setup.
-
false
Disable the optimizer. -
true
Enable optimizer with the default SVG Optimizer config. -
{ ... }
Enable optimizer with a custom options object.
svg4everybody
– false
Whether to include the SVG4Everybody
helper in your entries.
-
false
Don't add the helper. -
true
Add the helper with a configuration object of{}
. -
{ ... }
Add the helper with a custom options object.
glob
– {}
Options object to pass to glob
to find the sprites.
chunk
– 'spritemap'
Name of the chunk that will be generated.
deleteChunk
– true
Whether to delete the chunk after it's been emitted by webpack.
generateTitle
- true
Whether to generate a <title>
element containing the filename if no title is provided in the SVG.
generateUse
- true
Whether to include a <use>
element for each sprite within the generated spritemap to allow referencing symbols from CSS.
preserveComments
- false
Copy comments from the source sprite sheet into the output. Useful to preserve attribution requirements from projects such as fontawesome.
SVG4Everybody
SVG for Everybody adds SVG External Content support to all browsers.
It's a good idea to combine the svg-spritemap-webpack-plugin
with svg4everybody
. This can be done by passing an options object or true
to the svg4everybody
options key or by executing SVG4Everybody manually.