Getting Started

Overview

vite-plugin-svg-icons-ng is a high-performance SVG icon plugin built for Vite.

It automatically generates SVG sprites from local files and configurable injects them at runtime, allowing you to use SVG icons as easily as regular icons.

No manual sprite management, no extra requests, and no complex setup—just a clean and reusable icon system.

What you get

• File-based icon input, auto-generated SVG sprite output.
• Configurable HTML generation with script, inline, or none
• Optional client-side mount with no extra network request
• Stable behavior across dev, build, and SSR flows.
• Built-in cache + HMR for a smoother icon iteration loop.

If you want the background story, read Why This Plugin.

Quick Start

Step 1: Install

pnpm

pnpm add -D vite-plugin-svg-icons-ng

npm

npm i -D vite-plugin-svg-icons-ng

yarn

yarn add -D vite-plugin-svg-icons-ng

Step 2: Configure plugin

Add createSvgIconsPlugin in vite.config.ts / vite.config.js:

import { createSvgIconsPlugin } from 'vite-plugin-svg-icons-ng'

export default defineConfig({
  plugins: [
    createSvgIconsPlugin({
      iconDirs: ['src/icons'],
    }),
  ],
})

At this point, the SVG sprite can already be generated from your icon directories.

NOTE

Path resolution follows Vite: relative iconDirs are resolved from your Vite project root, while absolute paths are used as written. In monorepos, use an absolute path when the icon folder lives outside the current app root.

TIP

Default: htmlMode: 'inline', which injects the sprite into HTML. Use htmlMode: 'script' for runtime mount + dev HMR. If you use virtual:svg-icons/register, prefer htmlMode: 'none'.

Step 3: Continue

• Go to Usage to see how to use it next.
• Check Options for plugin configuration details.