Skip to content

options.md

Latest commit

 

History

History
226 lines (174 loc) · 9.4 KB

options.md

File metadata and controls

226 lines (174 loc) · 9.4 KB
Raw

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 Flow-esque way as follows:

new SVGSpritemapPlugin(string | string[], {
    input?: {
        options?: object
    },
    output?: {
        filename?: string,
        svg?: {
            sizes?: boolean
        },
        chunk?: {
            name?: string,
            keep?: boolean
        },
        svg4everybody?: boolean | object,
        svgo?: boolean | object
    },
    sprite?: {
        prefix?: string | function(file) | false,
        gutter?: number | false,
        generate?: {
            title?: boolean,
            symbol?: boolean | string,
            use?: boolean,
            view?: boolean | string
        }
    },
    styles?: boolean | string | {
        filename?: string,
        format?: 'data' | 'fragment',
        variables?: {
            sprites?: string,
            sizes?: string,
            variables?: string,
            mixin?: 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.

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.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.idify – require('html4-id')

Function that will be used to transform the filename of each sprite into a valid HTML id. The default function uses html4-id to generate a valid HTML4 id which has quite a few restrictions and since HTML5 allows pretty much anything as long as there's no whitespace it's possible to change this function. 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.

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.

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