Build an SVG Sprite for Vite/React/Vue (CLI & plugin routes)

Sprites let you ship one cached SVG file containing many icons. Below you’ll export clean per‑icon SVGs in Axialis IconVectors, then generate a symbol sprite two ways: with a Vite plugin or an NPM CLI. Finally, you’ll reference icons via <use> and cover caching/compat notes.

Export clean per‑icon SVGs from IconVectors

1. Open or create your icons:
   • File → Open… (Ctrl+O) or New Icon (Ctrl+N).
   • Prefer currentColor paints and a tidy viewBox (e.g., 0 0 24 24).
   • File → Export → Export Minified (Shift+Ctrl+M) for lean SVGs (SVGO‑friendly).

   

Route A — Vite plugin (auto sprite for React/Vue)

1. Install the plugin:

   npm i -D vite-plugin-svg-icons
   # or: pnpm add -D vite-plugin-svg-icons
   # or:  yarn add -D vite-plugin-svg-icons

   This plugin scans your src/icons folder, builds a symbol sprite, and injects it at runtime. Configure SVGO and a stable symbolId pattern.

2. Configure vite.config.ts

   import { defineConfig } from 'vite'
   import vue from '@vitejs/plugin-vue' // or: import react from '@vitejs/plugin-react'
   import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
   import path from 'path'
   
   export default defineConfig({
     plugins: [
       // vue(), or react(),
       createSvgIconsPlugin({
         iconDirs: [path.resolve(process.cwd(), 'src/icons')],
         symbolId: 'icon-[dir]-[name]',
         svgoOptions: {
           plugins: [
             { name: 'preset-default', params: { overrides: { removeViewBox: false } } },
             'removeDimensions',
             'prefixIds' // prevent ID collisions across icons
           ]
         },
         inject: 'body-last'
       })
     ]
   })

3. Register sprite & use icons

   // main.ts or main.tsx (React/Vue entry)
   import 'virtual:svg-icons-register'
   

   // React component
   export function Button() {
     return (
       <button className="inline-flex items-center gap-2 text-blue-600">
         <svg className="w-5 h-5" aria-hidden="true">
           <use href="#icon-check" /> {/* symbolId = icon-[dir]-[name] */} 
         </svg>
         Save
       </button>
     )
   }

   <!-- Vue SFC snippet -->
   <template>
     <button class="inline-flex items-center gap-2 text-emerald-600">
       <svg class="w-5 h-5" aria-hidden="true"><use href="#icon-check" /></svg>
       Save
     </button>
   </template>

   Note: Use href on <use>. The older xlink:href is deprecated; include it only as a fallback for legacy engines.

Route B — NPM CLI (build a static public/sprite.svg)

1. Install the CLI:

   npm i -D svg-sprite

   The CLI can output multiple modes; pick symbol for web icons.

2. Add a script that builds one sprite from all icons:

   {
     "scripts": {
       "build:sprite": "svg-sprite -s --symbol-dest public --symbol-sprite sprite.svg src/icons/*.svg"
     }
   }

   This compiles every SVG in src/icons into public/sprite.svg. Adjust paths as needed.

3. Reference icons in markup:

   <!-- External sprite placed under /public -->
   <svg class="icon w-5 h-5" aria-hidden="true">
     <use href="/sprite.svg#check" /> <!-- or: href="/sprite.svg#icons-check" if your tool prefixes -->
   </svg>

   • Caching: serve with far‑future cache headers; add a file hash or query (e.g., /sprite.abc123.svg or /sprite.svg?v=abc123).
   • Same‑origin: referencing an external sprite via <use> typically requires same‑origin or correct CORS headers.

When to pick which route

• Vite plugin: fastest DX, HMR updates, automatic injection; ideal for React/Vue SPAs.
• CLI: a single static file you can reuse across stacks (SSR, static sites, CMS). Great where you control build scripts.

IconVectors tips

• Minify and keep viewBox. Use File → Export → Export Minified (Shift+Ctrl+M).
• Theming: set fill="currentColor"/stroke="currentColor" so icons inherit text color.
• IDs: if your icons have id/gradients, enable an SVGO prefixIds pass (shown above) to avoid collisions in the combined sprite.

Troubleshooting

• Icon not found — confirm the generated symbolId (plugin option) or the sprite’s <symbol id="..."> names from the CLI output.
• Colors don’t change — ensure paths use currentColor or override fill/stroke in CSS on the wrapper <svg>.
• Legacy href — if supporting older browsers, add both href and xlink:href on <use>; modern browsers use href.