vite-plugin-svg-spritemap

Appearance

Options ​

The first argument is a glob path (using tinyglobby)

ts
// vite.config.js / vite.config.ts
import VitePluginSvgSpritemap from '@spiriit/vite-plugin-svg-spritemap'

export default {
  plugins: [VitePluginSvgSpritemap('./src/icons/*.svg')]
}

The second argument is an object with several options. See below for more details about each options.

The option types are exported

UserOptions types the whole object, so a config you build outside vite.config.ts still gets checked:

ts
import type { UserOptions, VariablesSpritemapMode } from '@spiriit/vite-plugin-svg-spritemap'

const spritemap: VariablesSpritemapMode = 'resolve'
export const icons: UserOptions = { prefix: 'icon-', variables: { spritemap } }

Every shape the plugin hands back is exported too, which is what an extracted styles.callback or idify needs: StylesCallback and its parts (StylesCallbackContext, SpritemapGenerator), Options, SvgMapObject, SvgDataUriMapObject, SvgVariables, and the option types themselves (OptionsStyles, OptionsVariables, StylesLang, StylesInclude, …). Inline callbacks infer without any of them.

ts
// vite.config.js / vite.config.ts
import VitePluginSVGSpritemap from '@spiriit/vite-plugin-svg-spritemap'

export default {
  plugins: [
    VitePluginSVGSpritemap('./src/icons/**/*.svg', {
      prefix: 'icon-',
      route: {
        url: '/__spritemap',
        name: 'spritemap',
      },
      output: {
        filename: '[name].[hash][extname]',
        name: 'spritemap.svg',
        use: true,
        view: false,
        hrefAttribute: 'xlink:href',
      },
      styles: {
        filename: 'src/scss/spritemap.scss',
        lang: 'scss',
        include: ['data', 'mixin'],
        names: {
          prefix: 'sprites-prefix',
          sprites: 'sprites',
          mixin: 'sprite',
          variables: 'sprites-variables',
        },
        sizes: {
          unit: 'px',
          base: 1,
        },
        callback: ({ content, options, createSpritemap }) => {
          return content
        },
      },
      types: {
        filename: 'src/types/spritemap.d.ts',
        groups: {
          Social: 'src/icons/social/*.svg',
        },
      },
      variables: {
        spritemap: 'preserve',
      },
      svgo: {
        plugins: [
          {
            name: 'removeStyleElement',
          },
        ],
      },
      oxvg: true,
      idify: (name, svg) => `icon-${name}-cheese`,
      injectSvgOnDev: true,
      gutter: 0,
    })
  ]
}

Every option is listed above, each with the shape it accepts rather than its default. Most of them also take a shorthand: output, styles and types accept a string or false, route a string, variables a boolean, and svgo/oxvg a boolean. svgo and oxvg are alternatives, not a pair: SVGO wins whenever it is installed and not set to false.

output ​

See Output options.

styles ​

See Styles options.

types ​

  • Type: false | string | { filename: string, groups?: Record<string, Glob> }
  • Default: false

File destination like src/types/spritemap.d.ts to enable type generation, or false to disable. You can also pass an object to additionally generate grouped types.

When enabled, generates a TypeScript type definition file containing union types of all valid icon names from the spritemap. This allows you to type your icon props for better type safety.

The generated file always includes the Icons type, plus two prefix-related types when a prefix is set:

  • Icons: Union type of all icon base IDs (without prefix)
  • Prefix: String literal type containing the prefix used in the spritemap (only generated when a prefix is set)
  • IconsPrefixed: Template literal type that combines the prefix with each icon ID, automatically generating 'sprite-icon1' | 'sprite-icon2' | 'sprite-icon3' (only generated when a prefix is set)

When prefix: false, only the Icons type is generated.

You can then use these types in your components.

Example
ts
// vite.config.ts
import VitePluginSvgSpritemap from '@spiriit/vite-plugin-svg-spritemap'

export default {
  plugins: [
    VitePluginSvgSpritemap('./src/icons/*.svg', {
      types: 'src/types/spritemap.d.ts',
    }),
  ],
}

This will generate a file src/types/spritemap.d.ts:

ts
// Generated by vite-plugin-svg-spritemap
export type Prefix = 'sprite-'

export type Icons = 'icon1' | 'icon2' | 'icon3'
export type IconsPrefixed = `${Prefix}${Icons}`

Grouped types ​

Pass the object form to split your icons into named sub-types alongside the global Icons type. This is useful when icons live in separate folders (e.g. icons, flags) and you want a dedicated type per folder.

  • filename: file destination (same as the string form above).
  • groups (optional): a map of TypeName → glob(s). Each glob is matched against icon file paths, and the matching icon IDs become a union type named after the key. A group matching nothing resolves to never. Group names that collide with Icons, Prefix or IconsPrefixed are skipped with a warning.
Example
ts
// vite.config.ts
import VitePluginSvgSpritemap from '@spiriit/vite-plugin-svg-spritemap'

export default {
  plugins: [
    VitePluginSvgSpritemap('./src/icons/**/*.svg', {
      types: {
        filename: 'src/types/spritemap.d.ts',
        groups: {
          Social: 'src/icons/social/*.svg',
          Ui: 'src/icons/ui/*.svg',
        },
      },
    }),
  ],
}

Given src/icons/social/{twitter,facebook}.svg and src/icons/ui/arrow.svg, this generates:

ts
// Generated by vite-plugin-svg-spritemap
export type Prefix = 'sprite-'

export type Icons = 'arrow' | 'facebook' | 'twitter'
export type IconsPrefixed = `${Prefix}${Icons}`

export type Social = 'facebook' | 'twitter'
export type SocialPrefixed = `${Prefix}${Social}`

export type Ui = 'arrow'
export type UiPrefixed = `${Prefix}${Ui}`

variables ​

  • Type: boolean | { spritemap?: 'preserve' | 'resolve' }
  • Default: { spritemap: 'preserve' }

Controls icon variables: a var(--name, default) inside an SVG presentation attribute, a style attribute or a <style> element becomes a themable value your SCSS/Stylus/Less mixin can override per call site. See the Variables guide.

Set to false to skip parsing entirely and generate no defaults map.

variables.spritemap ​

  • Type: 'preserve' | 'resolve'
  • Default: 'preserve'

How themable values are written into the generated spritemap (the <symbol>/<view> content served at the route and emitted as an asset).

  • 'preserve' keeps fill="var(--color, #fff)" verbatim, so any <use> element can be themed at runtime with real CSS custom properties, an external reference included.
  • 'resolve' bakes each default in (fill="#fff"), for maximum tooling compatibility.

This does not affect the generated stylesheet: the data URI there always has its defaults baked in, and compile-time substitution through the mixin works either way.

prefix ​

  • Type: string | false
  • Default: 'sprite-'

Define the prefix used for sprite id in <symbol>/<use>/<view>. You can set this option to false to disable the prefix.

This option is recommended to prevent conflict with other SVG or ids in your project.

svgo ​

  • Type: boolean | object
  • Default: false if SVGO not installed, true if SVGO is installed

Take an SVGO Options object. If true, it will use the default SVGO preset, if false, it will disable SVGO optimization.

WARNING

Since the version 3.0, you need to install svgo manually as a dependency of your project if you want vite-plugin-svg-spritemap to process SVG file with it.

bash
npm i -D svgo
bash
yarn add -D svgo
bash
pnpm add -D svgo
bash
bun add -D svgo

injectSvgOnDev ​

  • Type: boolean
  • Default: false

Inject the SVG Spritemap inside the body on dev. Useful for mitigating CORS issue with a Backend.

An icon's <style> element becomes a stylesheet of your page

The spritemap is inlined into the body, so a <style> element carried by one of your icons is a stylesheet of the document and restyles anything its selectors match, an editor's .cls-1 or .st0 included. Referenced through a URL, which is what the build does, the same rules stay inside the spritemap document, so this shows up in dev only. See Styles inside an icon.

idify ​

  • Type: (name: string, svg: object) => string
  • Default: name => name

Function allowing you to customize the id of each symbol of the spritemap svg.

route ​

  • Type: string | object
  • Default: '/__spritemap'

Change the route URL allowing you to have multiple instances of the plugin (see Multiple Instance).

You can also provide an object with the url and name properties. This is useful if you want to customize the name of the route in the Vite Dev Server and styles comments.

ts
// Example route object
const route = {
  url: '/__flags',
  name: 'Flags',
}

On build, a reference to this route is rewritten to the emitted asset URL, following Vite's base. See Deployment.

gutter ​

  • Type: number
  • Default: 0

Gutter (in pixels) between each sprite to help prevent overlap.

oxvg ​

  • Type: boolean | object
  • Default: false if OXVG not installed, true if OXVG is installed

Take an OXVG Options object. If false, it will disable OXVG optimization.

If true, it runs the same configuration as the svgo option, translated to OXVG jobs, so both optimizers enable the same set of jobs and disable the same ones.

TIP

SVGO takes precedence over OXVG: OXVG is only used when SVGO is not installed, or when svgo is set to false.

WARNING

You need to install @oxvg/napi 0.0.7. Earlier versions are not supported: they either ship no convertSvgoConfig at all, or translate the SVGO config differently.

The native binding for your platform comes with it, you do not have to add it yourself: @oxvg/napi lists all of them as optional dependencies and your package manager keeps the one that matches.

bash
npm i -D @oxvg/napi
bash
yarn add -D @oxvg/napi
bash
pnpm add -D @oxvg/napi
bash
bun add -D @oxvg/napi