@muxy/svg-spritemap-webpack-plugin

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 webpack output.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 a background-image.

• .scss/.sass Generates a Sass map containing the spritenames (excluding prefix) as keys and the sprite as values, comes with a sprite() 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.

License

This project is licensed under the MIT license.