svg-spritemap-webpack-plugin

# Options The `SVGSpritemapPlugin()` supports 2 arguments as input, the first being a [`glob`](https://www.npmjs.com/package/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. ```js new SVGSpritemapPlugin(); ``` Passing a string or an array of strings allows you to change the default pattern. ```js 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](https://www.typescriptlang.org/) interface as follows: ```js 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`](http://npmjs.com/package/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`](http://npmjs.com/package/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`](https://www.npmjs.com/package/svg4everybody#usage) 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`](http://npmjs.com/package/svgo). - `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](https://sass-lang.com/documentation/values/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. ```es6 // 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](https://css-tricks.com/svg-fragment-identifiers-work/). 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: ```js // Import it from a JavaScript bundle (styles: '~sprites.css') require('svg-spritemap-webpack-plugin/sprites.css'); ``` ```scss // 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](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#maps) containing the spritenames (excluding prefix) as keys and the sprite as values, comes with a `sprite()` [mixin](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#mixins). ```scss .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](/docs/variables.md) 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]((/docs/variables.md)) 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](http://lesscss.org/features/#variables-feature-overview) for each sprite based on the spritename (including prefix) with the sprite as value, comes with a `.sprite()` [mixin](http://lesscss.org/features/#mixins-feature). ```less .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](https://www.npmjs.com/package/mini-svg-data-uri) as background `url()`s. - `'fragment'` Generates URLs with [fragment identifiers](https://css-tricks.com/svg-fragment-identifiers-work/) as background `url()`s. This requires the `sprite.generate.view` option to be enabled and uses the webpack option [`output.publicPath`](https://webpack.js.org/configuration/output/#output-publicpath) to build a URL to the file. This type of setup requires some additional configuration, [see example](../examples/fragments) 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](variables.md). #### `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. ```es6 (content) => `[class*="sprite-"] { background-size: cover; } ${content}` ```