vite-plugin-svgr

5.2.0 verified Sat Apr 25 auth: no javascript

Vite plugin to transform SVG files into React components using SVGR. Current stable version is 5.2.0, with regular updates. Key differentiator: seamless integration with Vite, supports both import with ?react query and default export, optional SVGO optimization, and TypeScript declarations. Compared to alternatives like @svgr/webpack, it is Vite-native and simplifies SVG component usage in React projects.

Common errors

error Uncaught Error: @svgr/core tried to access @svgr/plugin-svgo but it's not installed ↓

cause SVGO plugin not installed but configured in svgrOptions.plugins.

fix

Install @svgr/plugin-svgo as a dependency.

error Module not found: Error: Can't resolve 'vite-plugin-svgr' ↓

cause Package not installed or mismatched Vite version.

fix

Run npm install -D vite-plugin-svgr and ensure Vite >=3 is installed.

error Cannot find module 'vite-plugin-svgr' or its corresponding type declarations. ↓

cause Missing TypeScript declaration for SVG imports.

fix

Add /// <reference types="vite-plugin-svgr/client" /> in a .d.ts file.

error The requested module 'vite-plugin-svgr' does not provide an export named 'default' ↓

cause Using CommonJS require in a project that expects ESM import.

fix

Use import svgr from 'vite-plugin-svgr' instead of require()

Warnings

breaking In v4.0.0, SVG import behavior changed: you must append ?react query to import as React component. Without it, you get the default export (SVG URL). ↓

fix Use import Logo from './logo.svg?react' instead of import Logo from './logo.svg'.

breaking v5.0.0 dropped Vite 2 support. Minimum Vite version is now 3.0.0. ↓

fix Upgrade Vite to v3+.

deprecated v4.0.0 changed the default export to the SVG file URL (string). If you relied on importing SVG as a component without ?react, it will break. ↓

fix Add ?react query to import React component.

gotcha SVGO is not enabled by default. If you expect SVGO optimization, you need to manually install @svgr/plugin-svgo and configure it via svgrOptions. ↓

fix Install @svgr/plugin-svgo and add to svgrOptions.plugins.

gotcha TypeScript declaration must be referenced with 'vite-plugin-svgr/client' not 'vite-plugin-svgr'. ↓

fix Add /// <reference types="vite-plugin-svgr/client" /> to your vite-env.d.ts.

breaking v3.2.0 re-added CJS entry, but since v4.0.0 the package is ESM-only. CommonJS require will fail. ↓

fix Use ESM imports (import) or set type: 'module' in package.json.

Install

npm install vite-plugin-svgr

yarn add vite-plugin-svgr

pnpm add vite-plugin-svgr

Imports

svgr
wrong
```
const svgr = require('vite-plugin-svgr')
```
correct
```
import svgr from 'vite-plugin-svgr'
```
Default import is the standard; CommonJS require may not work with ESM-only configuration.
default export with ?react
wrong
```
import Logo from './logo.svg'
```
correct
```
import Logo from './logo.svg?react'
```
The ?react query is required in v4+ to trigger SVG transformation. Without it, the file is treated as a regular asset URL.
TypeScript declaration
wrong
```
/// <reference types="vite-plugin-svgr" />
```
correct
```
/// <reference types="vite-plugin-svgr/client" />
```
The correct path is 'vite-plugin-svgr/client', not just 'vite-plugin-svgr'.
default export (SVG source)
```
import svgUrl from './logo.svg'
```
Importing without ?react gives the SVG file URL string, not a React component.

Quickstart

Demonstrates how to set up vite-plugin-svgr in a Vite project with React, including import syntax and TypeScript declaration.

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

export default defineConfig({
  plugins: [
    react(),
    svgr({
      svgrOptions: {
        icon: true,
        expandProps: 'end',
      },
      include: '**/*.svg?react',
    }),
  ],
});

// App.tsx
import ReactLogo from './logo.svg?react';

function App() {
  return (
    <div>
      <ReactLogo width={100} height={100} />
    </div>
  );
}

export default App;

// vite-env.d.ts
/// <reference types="vite-plugin-svgr/client" />