How to Import & Use SVG Icons in Vite: The Complete Developer Guide

1. Why Vite Handles SVGs Differently Than Webpack

Developers transitioning from Webpack-based boilerplates (such as Create React App) frequently expect import { ReactComponent as Icon } from './icon.svg' to work out of the box. In Create React App, Webpack bundled @svgr/webpack behind the scenes.

Vite is built on native ES modules (ESM) and Rollup. In Vite, importing any file with an .svg extension defaults to an asset URL reference:

// App.tsx
import viteLogo from '/vite.svg'; // returns "/vite.svg" or "/assets/vite.abc123.svg"

export function Header() {
  return <img src={viteLogo} alt="Vite Logo" className="w-6 h-6" />;
}

While this is optimal for large raster images or complex illustrations, it creates three major limitations for UI icons:

1. No CSS Color Synchronization: Because the SVG renders inside an isolated <img> context, CSS properties like fill, stroke, and currentColor cannot penetrate the boundary. Hover color changes become impossible without CSS filter hacks.
2. Extra Network Handshakes: If icons are not inlined or cached aggressively, rendering dozens of small <img src="..."> icons creates multiple HTTP requests or image decode overhead.
3. TypeScript Declaration Errors: Out of the box, TypeScript does not recognize .svg imports as React components or raw strings, throwing Cannot find module './icon.svg' or its corresponding type declarations. (TS2307).

2. Native Asset Imports: ?url vs ?raw vs ?inline

Vite provides built-in query suffixes that give you granular control over asset loading without installing third-party plugins. Understanding these query parameters is fundamental to mastering Vite's pipeline.

The Standard URL Query (?url)

Explicitly signals to Vite that you want the hashed asset URL. Vite emits the file into your production build directory (dist/assets/) and returns its public URL path:

import searchIconUrl from './assets/search.svg?url';

console.log(searchIconUrl); // Output in prod: "/assets/search.d3e4f5.svg"

The Raw String Query (?raw)

When you append ?raw, Vite loads the raw text content of the SVG file directly into your JavaScript bundle as an exported string. This allows client-side injection without external compiler plugins:

// Vanilla JS / React / Svelte
import heartSvgRaw from './assets/heart.svg?raw';

export function HeartIcon() {
  return (
    <span 
      className="inline-flex text-rose-500 hover:text-rose-600 transition-colors"
      dangerouslySetInnerHTML={{ __html: heartSvgRaw }} 
    />
  );
}

3. React: Full Component Integration with vite-plugin-svgr

For React projects, the premier industry solution is vite-plugin-svgr. It leverages @svgr/core to compile SVGs into real React functional components at build time, granting direct access to SVG props (className, style, onClick, fill, strokeWidth).

Step 1: Installation

npm install -D vite-plugin-svgr

Step 2: Vite Configuration (vite.config.ts)

In your vite.config.ts, register the plugin and specify your import query preferences:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import svgr from 'vite-plugin-svgr';

export default defineConfig({
  plugins: [
    react(),
    svgr({
      // Configure SVGR options
      svgrOptions: {
        icon: true, // Replace hardcoded width/height with 1em for responsive scaling
        svgo: true, // Run SVGO optimization automatically
        svgoConfig: {
          plugins: [
            {
              name: 'preset-default',
              params: {
                overrides: {
                  removeViewBox: false, // Essential: preserve viewBox for proper scaling!
                },
              },
            },
          ],
        },
      },
      // Restrict component transformation to files imported with '?react'
      include: '**/*.svg?react',
    }),
  ],
});

Step 3: TypeScript Declaration (src/vite-env.d.ts)

To eliminate TypeScript compiler warnings and enable autocomplete, add the client types reference to your src/vite-env.d.ts file:

/// <reference types="vite/client" />
/// <reference types="vite-plugin-svgr/client" />

If you prefer explicit typings for ?react imports, you can specify:

declare module '*.svg?react' {
  import React from 'react';
  const SVG: React.FC<React.SVGProps<SVGSVGElement> & { title?: string }>;
  export default SVG;
}

Step 4: Usage in Components

import React from 'react';
import CheckCircleIcon from './icons/check-circle.svg?react';

export function StatusCard({ isCompleted }: { isCompleted: boolean }) {
  return (
    <div className="flex items-center gap-3 p-4 bg-zinc-900 border border-zinc-800 rounded-lg">
      <CheckCircleIcon 
        className={`w-5 h-5 transition-colors ${
          isCompleted ? 'text-lime-400' : 'text-zinc-600'
        }`}
        strokeWidth={2}
      />
      <span className="text-zinc-200 text-sm font-medium">
        {isCompleted ? 'Verification Complete' : 'Pending Verification'}
      </span>
    </div>
  );
}

4. Vue 3: Dynamic Icons with vite-svg-loader

If you are building with Vue 3 or Nuxt 3 on Vite, the equivalent high-performance solution is vite-svg-loader. It compiles SVG files into Vue Single File Components (SFCs) on the fly.

Step 1: Installation

npm install -D vite-svg-loader

Step 2: Configuration (vite.config.js / vite.config.ts)

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import svgLoader from 'vite-svg-loader';

export default defineConfig({
  plugins: [
    vue(),
    svgLoader({
      svgoConfig: {
        multipass: true,
        plugins: [
          {
            name: 'preset-default',
            params: {
              overrides: {
                removeViewBox: false,
              },
            },
          },
        ],
      },
      defaultImport: 'url', // Default to 'url', require '?component' for Vue SFCs
    }),
  ],
});

Step 3: Component Usage in Vue 3

With vite-svg-loader, you can import the same SVG file as a component, as a URL, or as raw code depending on your specific needs:

<script setup lang="ts">
// Import as an interactive Vue component
import BellIcon from '@/assets/icons/bell.svg?component';
// Or as a static URL string
import bellUrl from '@/assets/icons/bell.svg?url';
</script>

<template>
  <button class="icon-button">
    <!-- Renders inline SVG with full CSS styling and Vue props -->
    <BellIcon class="w-6 h-6 text-zinc-400 hover:text-lime-400" />
    <span class="sr-only">Notifications</span>
  </button>
</template>

5. The Universal Solution: unplugin-icons

When building enterprise applications that require dozens or hundreds of icons across disparate sets (such as Lucide, Tabler, Heroicons, and Phosphor), converting every SVG individually creates enormous maintenance baggage.

The modern gold standard across Vite, Rollup, Webpack, Nuxt, and Svelte is unplugin-icons. It connects to open-source icon sets (via Iconify's datasets) and compiles only the icons you use directly into your framework components at build time.

Installation

npm install -D unplugin-icons @iconify/json

Configuration

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import Icons from 'unplugin-icons/vite';

export default defineConfig({
  plugins: [
    react(),
    Icons({
      compiler: 'jsx',
      jsx: 'react',
      autoInstall: true, // Automatically installs icon packs as you import them
      scale: 1.2, // Default size scaling (1em * scale)
      defaultClass: 'inline-block shrink-0',
    }),
  ],
});

Importing Icons on Demand

You can now import icons from any popular open-source library simply using the virtual path convention ~icons/{collection}/{icon_name}:

import IconSearch from '~icons/lucide/search';
import IconBrandGithub from '~icons/tabler/brand-github';
import IconSparkles from '~icons/ph/sparkle';

export function Toolbar() {
  return (
    <div className="flex gap-4 items-center">
      <IconSearch className="text-zinc-400 hover:text-lime-400 w-5 h-5 cursor-pointer" />
      <IconBrandGithub className="text-zinc-400 hover:text-white w-5 h-5" />
      <IconSparkles className="text-amber-400 w-5 h-5" />
    </div>
  );
}

Because unplugin-icons resolves icons at build time, it performs 100% dead-code elimination (tree-shaking). Only the exact SVG paths for search, brand-github, and sparkle enter your production bundle, saving megabytes compared to legacy icon font libraries.

6. Architectural Decision Matrix: Which Approach to Choose?

Each method carries trade-offs between setup complexity, bundle size, CSS styleability, and runtime performance. Use this decision matrix to pick the right strategy for your web application:

7. Production Performance & SVGO Optimization

When importing dozens of SVGs directly into your JavaScript bundle, SVGO optimization is critical. Raw SVGs exported from design software like Figma or Adobe Illustrator contain unneeded metadata, XML namespaces, hidden editor layers, and explicit hardcoded colors that break UI themes.

1. Always Strip Hardcoded Width and Height

Configure SVGO to remove width and height attributes while strictly preserving the viewBox. This allows the icon to scale fluidly according to parent CSS classes (such as w-5 h-5 or width: 1.25rem):

// svgo.config.js
module.exports = {
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          removeViewBox: false, // NEVER remove viewBox in responsive UI
        },
      },
    },
    'removeDimensions', // Strips width and height attributes
  ],
};

2. Convert Hardcoded Fills and Strokes to currentColor

If your SVG contains fill="#000000" or stroke="#333333", it will ignore CSS color utility classes. Replace hardcoded hex codes with currentColor so the SVG automatically inherits the typography color of its parent button or text container:

<!-- Before: Hardcoded fill ignores CSS -->
<svg viewBox="0 0 24 24" fill="#1E293B">...</svg>

<!-- After: Responsive to parent typography color -->
<svg viewBox="0 0 24 24" fill="currentColor">...</svg>

8. Frequently Asked Questions