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.

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: '__spritemap',
      output: {
        filename: '[name].[hash][extname]',
        name: 'spritemap.svg',
        view: false,
        use: true,
      },
      svgo: {
        plugins: [
          {
            name: 'removeStyleElement',
          },
        ],
      },
      injectSvgOnDev: true,
      idify: (name, svg) => `icon-${name}-cheese`,
      gutter: 0,
      styles: {
        lang: 'scss',
        filename: 'src/scss/spritemap.scss',
        include: ['mixin', 'variables'],
        names: {
          prefix: 'sprites-prefix',
          sprites: 'sprites',
          mixin: 'sprite',
        },
        callback: ({ content, options, createSpritemap }) => {
          return content
        }
      },
      types: 'src/types/spritemap.d.ts'
    })
  ]
}

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}`

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.

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',
}

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 switching optimizer does not change the output. That translation needs @oxvg/napi 0.0.6 or above; below that it falls back to the OXVG default preset.

TIP

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

WARNING

An options object is the complete list of jobs to run, it does not extend the default described above. Any job missing from your object is not run at all:

js
svgSpritemap('./src/icons/*.svg', {
  // prefixIds runs, and nothing else does: no path or attribute optimization
  oxvg: { prefixIds: { /* ... */ } },
})

So unlike svgo, you cannot keep the default and tweak a single job. OXVG has no equivalent of SVGO's preset-default overrides, and passing an object starts from nothing.

WARNING

You need to install @oxvg/napi (0.0.4-1 or above) and the corresponding native binding dependency for your platform.

bash
npm i -D @oxvg/napi
npm i -D @oxvg/napi-darwin-arm64 #macOS ARM64 (Apple Silicon)
npm i -D @oxvg/napi-darwin-x64 #macOS x64 (Intel)
npm i -D @oxvg/napi-linux-x64-gnu #Linux x64 (GNU)
npm i -D @oxvg/napi-win32-x64-msvc #Windows x64 (MSVC)
bash
yarn add -D @oxvg/napi
yarn add -D @oxvg/napi-darwin-arm64 #macOS ARM64 (Apple Silicon)
yarn add -D @oxvg/napi-darwin-x64 #macOS x64 (Intel)
yarn add -D @oxvg/napi-linux-x64-gnu #Linux x64 (GNU)
yarn add -D @oxvg/napi-win32-x64-msvc #Windows x64 (MSVC)
bash
pnpm add -D @oxvg/napi
pnpm add -D @oxvg/napi-darwin-arm64 #macOS ARM64 (Apple Silicon)
pnpm add -D @oxvg/napi-darwin-x64 #macOS x64 (Intel)
pnpm add -D @oxvg/napi-linux-x64-gnu #Linux x64 (GNU)
pnpm add -D @oxvg/napi-win32-x64-msvc #Windows x64 (MSVC)
bash
bun add -D @oxvg/napi
bun add -D @oxvg/napi-darwin-arm64 #macOS ARM64 (Apple Silicon)
bun add -D @oxvg/napi-darwin-x64 #macOS x64 (Intel)
bun add -D @oxvg/napi-linux-x64-gnu #Linux x64 (GNU)
bun add -D @oxvg/napi-win32-x64-msvc #Windows x64 (MSVC)