vite-plugin-svg-spritemap

Appearance

Styles options ​

styles ​

  • Type: false | object | string
  • Default: false

File destination like src/css/spritemap.css or styles object (see below available options)

styles.filename ​

  • Type: string
  • Default: undefined

The destination of the stylesheet file like your source folder.

styles.lang ​

  • Type: 'less' | 'scss' | 'styl' | 'css' | undefined
  • Default: undefined

Enforce the styles language generated by the plugin. By default, this will be detected based on the extension of the filename. If not found, it will fallback to css.

styles.include ​

  • Type: boolean | Array<'data' | 'mixin' | 'bg' | 'mask' | 'bg-frag'>
  • Default: true

This allows you to choose what to include in the styles output payload.

true is everything the language can emit, so ['data', 'mixin'] for SCSS/Less/Stylus and ['bg', 'mask', 'bg-frag'] for CSS. false is nothing at all, leaving only what a callback returns.

An array is a free subset of the five entries rather than one of those two sets: each language reads the ones that apply to it and ignores the rest, so ['mask'] gives you the mask classes alone in CSS. The entries are exported as StylesInclude, and StylesIncludeInput adds the deprecated alias below.

'data' is the declarations block the mixin reads: the prefix, the sprites map (each icon's data URI, width and height) and, when an icon declares a variable, the defaults map. CSS has no such block, so the entry emits nothing there.

'mixin' cannot stand on its own: it looks every sprite up in the declarations 'data' writes, so ['mixin'] is read as ['mixin', 'data'] and warns. The reverse is fine, ['data'] gives you the declarations with no mixin.

Deprecated

'data' was named 'variables' until 7.2.0, when an icon gained variables of its own. The old entry is still accepted, renamed with a warning, and will be dropped in the next major. Icon variables are the variables option, not an include entry: variables: false drops the defaults map and the compile-time substitution while keeping the sprites map and a working mixin.

styles.names ​

  • Type: { prefix: string, sprites: string, mixin: string, variables: string }
  • Default: { prefix: 'sprites-prefix', sprites: 'sprites', mixin: 'sprite', variables: 'sprites-variables' }

Allows you to customize the variables/mixin names of the generated Sass/Less/Stylus.

variables names the map holding each sprite's variable defaults.

styles.sizes ​

  • Type: { unit: string, base: number }
  • Default: { unit: 'px', base: 1 }

Allows you to customize the CSS unit and base value used for width/height output in the generated stylesheets. This is useful for outputting relative units like em or rem instead of pixels.

Example: Using em units ​

js
VitePluginSvgSpritemap('./src/icons/*.svg', {
  styles: {
    filename: 'src/styles/spritemap.scss',
    sizes: {
      unit: 'em',
      base: 16
    }
  }
})

With this configuration, a sprite with dimensions 32x32 pixels will output as 2em x 2em (32 / 16 = 2).

This enables responsive icon sizing using font-size:

css
.icon {
  width: 1em;
  height: 1em;
}

.container {
  font-size: 200%; /* Icon will be twice the size */
}

styles.callback ​

  • Type: Function | undefined
  • Default: undefined

Allows you to customize the output of the generated styles file (see Customize Styles Outputs).