svg-sprite-loader

6.0.11 verified Sat Apr 25 auth: no javascript

Webpack loader for creating SVG sprites, enabling inline SVG usage via <use> tags. Current stable version 6.0.11, with a release cadence of roughly 2-3 major versions per year. Key differentiators: automatic runtime injection, isomorphic support for node/browser, customizable runtime generators, and external sprite file extraction for CSS/HTML imports. Supports webpack 5 (v6+), webpack 4 (v5), and earlier versions. Maintained by JetBrains.

Common errors

error Error: Module not found: Error: Can't resolve 'svg-sprite-loader' ↓

cause Missing or incorrect installation of svg-sprite-loader

fix

Run 'npm install svg-sprite-loader --save-dev' or 'yarn add svg-sprite-loader -D'.

error TypeError: Cannot read property 'replace' of undefined ↓

cause The loader options object not provided, or symbolId function returns undefined

fix

Ensure options is an object; if using symbolId function, return a string.

error Error: MultiCompiler was not fully processed: the output filesystem ... ↓

cause Webpack 5 multi-configuration incompatibility with svg-sprite-loader v5 (fixed in v6)

fix

Upgrade to v6.0.0 or later, or adjust multi-config setup.

Warnings

breaking In v6.0.0, dropped support for webpack <5. Upgrade webpack to 5.x or stay on v5.x. ↓

fix Update webpack to version 5 or later. If using webpack 4, continue using v5.2.1.

breaking In v5.0.0, the context param passed to runtime generators was changed from compilation root to folder where SVG image is located. This may break custom generators. ↓

fix Update custom runtime generators to use the new context meaning.

deprecated runtimeCompat option is deprecated and will be removed in future versions. ↓

fix Use runtimeOptions instead.

gotcha ES module export is autoconfigured based on webpack version; manual esModule option may be needed for consistent behavior. ↓

fix Explicitly set esModule: true if using ESM imports, false for CommonJS.

gotcha In extract mode (extract: true), the returned object has a url field instead of content. Confirm runtime compatibility. ↓

fix Use object.url for external sprite file references.

Install

npm install svg-sprite-loader

yarn add svg-sprite-loader

pnpm add svg-sprite-loader

Imports

default
wrong
```
const icon = require('./icon.svg')
```
correct
```
import icon from './icon.svg'
```
ESM default import returns an object with id, viewBox, content (or url in extract mode).

symbolId

wrong

import { symbolId } from 'svg-sprite-loader'

correct

import { symbolId } from 'svg-sprite-loader/runtime'

symbolId is a runtime export, not from the main package.

SpriteSymbol

wrong

const SpriteSymbol = require('svg-sprite-loader').SpriteSymbol

correct

import SpriteSymbol from 'svg-sprite-loader/lib/sprite-symbol'

Internal class, not exposed in public API; use only if extending runtime.

Quickstart

Configures webpack to load SVG files as sprite symbols, using svgo for optimization. Imports return symbol objects usable with <use>.

// webpack.config.js
const path = require('path');
module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js' },
  module: {
    rules: [
      {
        test: /\.svg$/,
        use: [
          { loader: 'svg-sprite-loader', options: { esModule: true } },
          'svgo-loader'
        ]
      }
    ]
  }
}