vite-plugin-svg-spritemap weekly downloads statistics

vite-plugin-svg-spritemap

A Vite plugin that bundles a directory of .svg files into a single spritemap of <symbol> elements.

• Optionally generates a TypeScript union of the icon names, so a typo is a build error
• Optimizes icons with SVGO
• Hoists <defs> to the top level and namespaces their ids, so gradients, patterns and masks keep working and never collide
• Optional <view> output for <img> and CSS background-image
• Content hashing for long-term caching
• HMR: editing an icon swaps it in place, without reloading the page

Requirements

Vite 5–8, Node 20.19+. ESM only.

Installation

npm install -D vite-plugin-svg-spritemap

Usage

// vite.config.ts
import { defineConfig } from 'vite';
import { svgSpritemap } from 'vite-plugin-svg-spritemap';

export default defineConfig({
  plugins: [svgSpritemap({ pattern: 'src/icons/*.svg' })],
});

Each file becomes a <symbol> whose id is the filename without extension — src/icons/arrow.svg → #arrow.

<svg>
  <use href="/spritemap.svg#arrow"></use>
</svg>

The sprite is written to the build output directory and served at the same path in dev. Use the deprecated xlink:href instead of href if you need to support legacy browsers.

React

export const Icon = ({ name }: { name: string }) => (
  <svg>
    <use href={`/spritemap.svg#${name}`} />
  </svg>
);

Turn on types to make name a union of the actual icon names instead of string.

Options

Option	Type	Default	Description
pattern	string	—	Glob of the SVG files to include. Required.
filename	string	spritemap.svg	Output filename. Supports [hash].
symbolId	string | (file, name) => string	[name]	Template for the symbol ids. Tokens: [name], [dir]. A function gets the file path and the base name.
svgo	SVGOConfig | boolean	true	SVGO optimization. Pass a config object to customize it.
currentColor	boolean	false	Replace colors with currentColor so icons inherit CSS color.
view	boolean	false	Also emit <view> elements, so icons work in <img> and CSS background-image.
hmr	boolean	true	Update icons in place in dev. Set to false to reload the whole page instead.
types	boolean | string	false	Generate a module with the icon names. true writes src/spritemap-icons.ts; pass a path to change it.

The sprite is emitted as a Rollup asset, so other plugins — compression, for instance — see it like any other build output.

Duplicate names

Ids have to be unique within the sprite. With a recursive glob, icons/ui/close.svg and icons/nav/close.svg both want #close; the plugin keeps the first and warns about the second. Set symbolId to tell them apart:

svgSpritemap({ pattern: 'src/icons/**/*.svg', symbolId: '[dir]-[name]' });
// → #ui-close, #nav-close

A literal prefix is just part of the template — symbolId: 'icon-[name]' gives #icon-arrow.

Ids declared inside an icon (gradients, masks, clip paths) are namespaced automatically, so two icons that both define id="a" no longer overwrite each other.

Long-term caching

Put [hash] in filename and the name changes only when the icons do:

svgSpritemap({ pattern: 'src/icons/*.svg', filename: 'sprite-[hash].svg', types: true });

The generated module exports the resolved URL, so nothing has to be hardcoded:

import { iconHref, spritemapUrl } from './spritemap-icons';

spritemapUrl; // '/sprite-a1b2c3d4.svg'
iconHref('arrow'); // '/sprite-a1b2c3d4.svg#arrow'

The dev server keeps a stable [hash] of dev, so references do not go stale on edit.

Icons in <img> and CSS

A <symbol> is never rendered, which is why an <img> pointing at one comes out blank. Turn view on and each icon also gets a <view> framing it, addressable with a -view suffix:

<img src="/spritemap.svg#arrow-view" width="24" height="24" />

.icon {
  background-image: url('/spritemap.svg#arrow-view');
}

Icons used this way cannot inherit currentColor — the browser renders them as an independent document.

Typed icon names

Turn types on and the plugin writes a module listing every symbol in the sprite:

svgSpritemap({ pattern: 'src/icons/*.svg', types: true });

// src/spritemap-icons.ts — generated, do not edit
export const spritemapUrl = '/spritemap.svg';

export const iconNames = ['arrow', 'close'] as const;

export type IconName = (typeof iconNames)[number];…