options.md

Options

The SVGSpritemapPlugin() supports 2 arguments as input, the first being a glob pattern that will be used to find the sprites, the second is an optional object containing additional configuration options.

Simple usage
Adding the plugin without passing any options will result in all the defaults being used.

new SVGSpritemapPlugin();

Passing a string or an array of strings allows you to change the default pattern.

new SVGSpritemapPlugin('images/sprites/**/*.svg');

new SVGSpritemapPlugin([
    'images/logos/**/*.svg',
    'images/icons/**/*.svg'
]);

Advanced usage
Passing an object as the second argument allows you to change specific options, this options object can be described in a TypeScript interface as follows:

new SVGSpritemapPlugin(string | string[], {
    input?: {
        options?: object,
        allowDuplicates?: boolean,
    },
    output?: {
        filename?: string,
        svg?: {
            sizes?: boolean,
            attributes?: object
        },
        chunk?: {
            name?: string,
            keep?: boolean
        },
        svg4everybody?: boolean | object,
        svgo?: boolean | object
    },
    sprite?: {
        prefix?: string | (file) => string | false,
        gutter?: number | false,
        generate?: {
            title?: boolean,
            symbol?: boolean | string,
            use?: boolean,
            view?: boolean | string
        }
    },
    styles?: boolean | string | {
        filename?: string,
        format?: 'data' | 'fragment',
        keepAttributes?: boolean,
        variables?: {
            sprites?: string,
            sizes?: string,
            variables?: string,
            mixin?: string
        },
        callback?: (content) => string
    }
});

---

pattern - '**/*.svg'

Pattern (or an array of patterns) for glob used to find the SVGs that should be in the spritemap.

options

Input

The input object contains the configuration for the input of the plugin.

input.options – {}

Options object to pass to glob to find the sprites.

input.allowDuplicates – false

Allow the usage of the same input SVG multiple times. This option work well together with the sprite.idify option to set a different name in the output file.

Output

The output object contains the configuration for the main output (SVG) of the plugin.

output.filename – 'spritemap.svg'

Filename of the generated file (located at the webpack output.path), [hash] and [contenthash] are supported.

output.svg.sizes

Whether to include the width and height attributes on the root SVG element. The default value for this option is based on the value of the sprite.generate.use option but when specified will always overwrite it.

output.svg.attributes -- {}

Custom attributes to add to the root SVG element. This should be an object, with key attribute names, and value attribute values, e.g. { id: 'my-svg-id' }. By default no attributes will be added.

output.chunk.name – 'spritemap'

Name of the chunk that will be generated.

output.chunk.keep – false

Whether to keep the chunk after it's been emitted by webpack.

output.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.

output.svgo – true

Options object to pass to SVG Optimizer.

• false
  Disable the optimizer.
• true
  Enable optimizer with the default SVG Optimizer config.
• { ... }
  Enable optimizer with a custom options object.

Sprite

The sprite object contains the configuration for the generated sprites in the output spritemap.

sprite.prefix – 'sprite-'

Prefix added to sprite id in the spritemap. It's possible to pass a function for more advanced situations, the full path to the current sprite will be passed as the first argument.

This value will also be used for the class/spritename in the generated styles, the exact implementation and usage differs between style implementations follows:

• .css
  Used as a prefix for the classname.
• .scss/.sass
  Stripped from the variable name since the Sass implementation is based on maps.
• .less
  Used as a prefix for the variable.

sprite.prefixStylesSelectors – false

Whether to also prefix any selectors that are generated in the styles file, if enabled.

sprite.idify – idify

Function that will be used to transform the filename of each sprite into a valid HTML id. The default function strips all whitespace as this is the only restriction according to the HTML5 specification. Passing false will result in the filename getting used as-is.

// Generate HTML5 id's
(filename) => filename.replace(/[\s]+/g, '-');

sprite.gutter – 0

Amount of pixels added between each sprite to prevent overlap.

sprite.generate.title - true

Whether to generate a <title> element containing the filename if no title is provided in the SVG.

sprite.generate.symbol - true

Whether to include a <symbol> element for each sprite within the generated spritemap. Passing a string will use the value as a postfix for the id attribute.

sprite.generate.use - false

Whether to include a <use> element for each sprite within the generated spritemap to allow referencing symbols from CSS.

sprite.generate.view - false

Whether to include a <view> element for each sprite within the generated spritemap to allow referencing via fragment identifiers. Passing a string will use the value as a postfix for the id attribute.

sprite.generate.dimensions - false

Whether to keep each SVG height and width attributes and add them to the generated symbol.

Styles

The styles object contains the configuration for the generated styles, it's disabled (false) by default. A string can be used as the value which will then be used for the styles.filename option.

styles.filename – '~sprites.css'

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.

• '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.

  The sprite() mixin accepts the following arguments:

  • name: Identifier of the sprite, based on the filename
  • variables: Sass map containing variables to alter the sprite
  • include-size: Whether to include a size-related property (defaults to false)
  • property: Which property to use (defaults to background), mask would be a valid alternative

• .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);
  }

styles.keepAttributes – false

Whether to include the original SVG attributes in the generated styles.

styles.format – 'data'

Format of the styles that will be generated, the following values are valid:

• 'data'
  Generates data URIs as background url()s.
• 'fragment'
  Generates URLs with fragment identifiers as background url()s. This requires the sprite.generate.view option to be enabled and uses the webpack option output.publicPath to build a URL to the file. This type of setup requires some additional configuration, see example for more information.

styles.variables.sprites – 'sprites'

Name for the SCSS variable that is used for the Sass map containing sprites.

styles.variables.sizes – 'sizes'

Name for the SCSS variable that is used for the Sass map containing size information for each sprite.

styles.variables.variables – 'variables'

Name for the SCSS variable that is used for the Sass map containing user-defined variables.

styles.variables.mixin – 'sprite'

Name for the SCSS variable that is used for the Sass mixin.

styles.callback – undefined

Provide a callback function to process the styles content before it is saved.

(content) => `[class*="sprite-"] { background-size: cover; } ${content}`