# external-svg-sprite-loader

> A webpack loader and plugin that generate SVG sprites out of a collection of SVG files used in your JS and CSS files

Latest version **7.3.0** (published 2025-01-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install external-svg-sprite-loader
pnpm add external-svg-sprite-loader
yarn add external-svg-sprite-loader
bun add external-svg-sprite-loader
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 7.3.0 |
| Published | 2025-01-02 |
| First published | 2016-10-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=10.13.0 |
| Dependencies | 5 |
| Unpacked size | 37 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 63 |
| Author | Bruno Sampaio |
| Maintainers | bensampaio |
| Keywords | svg, webpack, webpack-loader |

## Links

- npm: https://www.npmjs.com/package/external-svg-sprite-loader
- Repository: http://github.com/bensampaio/external-svg-sprite-loader
- npm.io page: https://npm.io/package/external-svg-sprite-loader

## Dependencies (5)

- [cheerio](https://npm.io/package/cheerio.md) ^0.22.0
- [imagemin](https://npm.io/package/imagemin.md) ^7.0.1
- [loader-utils](https://npm.io/package/loader-utils.md) ^2.0.0
- [imagemin-svgo](https://npm.io/package/imagemin-svgo.md) ^8.0.0
- [lodash.escaperegexp](https://npm.io/package/lodash.escaperegexp.md) ^4.1.2

## Alternatives

- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads

## Recent versions

- 7.3.0 (latest) — 2025-01-02
- 7.1.0-beta.2 (beta) — 2020-11-10
- 7.2.0 — 2021-06-10
- 7.1.2 — 2021-02-18
- 6.0.2 — 2021-02-18
- 7.1.1 — 2020-11-12
- 7.1.0 — 2020-11-10
- 7.1.0-beta.0 — 2020-11-09
- 7.0.1 — 2020-11-09
- 7.1.0-beta.1 — 2020-11-09
- 7.0.0 — 2020-11-05
- 6.0.1 — 2020-07-06
- 6.0.0 — 2020-06-30
- 5.0.1 — 2019-08-16
- 5.0.0 — 2019-07-05
- … 29 more at https://npm.io/package/external-svg-sprite-loader/versions

## README

# External SVG Sprite

[![npm version](https://badge.fury.io/js/external-svg-sprite-loader.svg)](https://badge.fury.io/js/external-svg-sprite-loader)
[![Build Status](https://travis-ci.org/bensampaio/external-svg-sprite-loader.svg?branch=master)](https://travis-ci.org/bensampaio/external-svg-sprite-loader)

A loader and plugin for webpack that converts all your SVGs into symbols and merges them into a SVG sprite.

**Important**: There is a breaking change when moving from v3 to v4. Check the [release notes](https://github.com/bensampaio/external-svg-sprite-loader/releases/tag/v4.0.0).

## Requirements

You will need NodeJS v6+, npm v3+ and webpack 4.

To make it work in older browsers, like Internet Explorer, you will also need [SVG for Everybody](https://github.com/jonathantneal/svg4everybody) or [svgxuse](https://github.com/Keyamoon/svgxuse).

## Installation

```bash
npm i external-svg-sprite-loader
```

or

```bash
yarn add external-svg-sprite-loader
```

## Options

### Loader options

- `name` - relative path to the sprite file (default: `img/sprite.svg`). The `[contenthash]` placeholder is supported.
- `iconName` - name for the icon symbol (default: `icon-[name]-[hash:5]`).
- `publicPath` - custom public path to be used instead of webpack `output.publicPath`. This option might be useful when your webpack `output.publicPath` is set to a different scheme/host/port (e.g.: when you use a CDN). This is because currently the SVG sprite cannot be served from another domain ([read more](https://stackoverflow.com/questions/32850536/cross-domain-svg-sprite)).
- `svgoOptions` - custom options to be passed to svgo. If you set this option then make sure you add `{ removeViewBox: false }` to the `plugins` otherwise this loader won't work.

### Plugin options

- `emit` - determines if the sprite is supposed to be emitted (default: true). Useful when generating server rendering bundles where you just need the SVG sprite URLs but not the sprite itself.
- `sprite` - SVG sprite options (default: {startX: 0, startY: 0, deltaX: 0, deltaY: 0, iconHeight: 50, rowWidth: 1000}). StartX and StartY - beginning sprite position, DeltaX and DeltaY - space between icons. IconHeight - Icon height in the sprite (just for the comfort).

## Usage

If you have the following webpack configuration:

```js
// webpack.config.js

import path from 'path';

import SvgStorePlugin from 'external-svg-sprite-loader';

module.exports = {
    mode: 'development',
    module: {
        rules: [
            {
                loader: SvgStorePlugin.loader,
                test: /\.svg$/,
            },
        ],
    },
    output: {
        path: path.join(__dirname, 'public'),
        publicPath: '/',
    },
    plugins: [
        new SvgStorePlugin({
            sprite: {
                startX: 10,
                startY: 10,
                deltaX: 20,
                deltaY: 20,
                iconHeight: 20,
            },
        }),
    ],
};
```

You will be able to import your SVG files in your JavaScript files as shown below.
The imported SVG will always correspond to a JavaScript object with keys `symbol`, `view` and `viewBox`:
- The `symbol` url can be used on a `<use>` tag to display the icon;
- The `view` url is supposed to be used in CSS;
- The `viewBox` value is required by some browsers on the `<svg>` tag;
- The `title` value can be used on the `<svg>` tag for accessibility.

The URLs will have the following format:
- `symbol`: `webpackConfig.output.publicPath`/`loader.name`#`loader.iconName`
- `view`: `webpackConfig.output.publicPath`/`loader.name`#view-`loader.iconName`

```js
/*
 * {
 *  symbol: '/public/img/sprite.svg#icon-logo',
 *  view: '/public/img/sprite.svg#view-icon-logo',
 *  viewBox: '0 0 150 100',
 *  title: 'Logo'
 * }
 */
import logo from './images/logo.svg';

const Logo = () => (
   <svg viewBox={logo.viewBox} title={logo.title} role="img">
       <use xlinkHref={logo.symbol} />
   </svg>
);
```

In CSS files, you can import your SVG files as shown bellow (assuming you are using the [MiniCssExtractPlugin](https://github.com/webpack-contrib/mini-css-extract-plugin)).
The imported value will be converted into the `view` url shown above.

```css
.special-icon {
    /* the url will be replaced with the url to the sprite */
    background-image: url('./icons/special.svg') no-repeat 0;
}
```

When a SVG is added, removed or changed, the sprite will be re-generated and all files referencing it will be updated. When no `[contenthash]` is used in the `name` option, a cache-busting will be added to the URL so that the browser is forced to re-download the sprite.

## Examples

You can find working examples in the `examples` folder. To test the React example under the `examples/react` folder run:

```bash
npm install
npm run start:dev
```

And then you can see the result in `http://localhost:3000`.

There's some additional commands that you may try:

- `npm run start:dev:hot` to check if sprite updates work with [Hot Module replacement](https://webpack.js.org/guides/hot-module-replacement/).
- `npm run start:dev:no-hash` to check if sprite updates work, even if the outputted file is the same.
- `npm run start:dev:hot-no-hash` to check if sprite updates work with [Hot Module replacement](https://webpack.js.org/guides/hot-module-replacement/), even if the outputted file is the same.
- `npm run build:prd && npm run start:prd` to test a production build.

## Contributing

First of all, **thank you** for contributing, **you are awesome**.

Here are a few rules to follow in order to ease code reviews, and discussions before maintainers accept and merge your work:

- Make sure your commit messages make sense (don't use `fix tests`, `small improvement`, `fix 2`, among others).
- Before creating a pull request make sure of the following:
    - your code is all documented properly;
    - your code passes the ESLint rules;
    - variable, function and class names are explanatory enough;
    - code is written in ES2015.
- When creating a pull request give it a name and description that are explanatory enough. In the description detail everything you are adding, do not assume we will understand it from the code.

Thank you!

## License

MIT (http://www.opensource.org/licenses/mit-license.php)

---
_Source: https://npm.io/package/external-svg-sprite-loader · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._