JavaScript CSS
Latest commit a7d9ab2 May 26, 2018
Permalink
Failed to load latest commit information.
.github fix: error link in pr template May 15, 2018
assets/css Docs styles cosmetics Apr 29, 2017
env chore: add memory-fs as dev dep Mar 12, 2018
examples docs: drop outdated examples readme & update root readme Mar 22, 2018
lib feat: support symbol id interpolator as function May 26, 2018
runtime feat(runtime): add ability to create sprite from existing DOM node Aug 16, 2017
scripts chore(build): make possible to build examples with webpack 4 Mar 19, 2018
test feat: add webpack 4 support Mar 8, 2018
.codeclimate.yml ci(codeclimate): update config May 8, 2017
.cz-config.js chore(commitizen): add runtime-generator scope May 22, 2017
.editorconfig Add .editorconfig Oct 2, 2015
.eslintignore Fix eslint issues Apr 24, 2017
.eslintrc Update eslint Apr 12, 2017
.gitignore chore(.gitignore): add .DS_Store Aug 15, 2017
.npmignore Add .npmignore Aug 6, 2015
.nvmrc Still trying to fix travis ci config Apr 29, 2017
.nycrc feat: add webpack 4 support Mar 8, 2018
.travis.yml feat: add webpack 4 support Mar 8, 2018
2.0.md Linkify issues id in 2.0 docs Apr 29, 2017
CHANGELOG.md chore(release): 3.9.0 May 26, 2018
CODE_OF_CONDUCT.md chore(code of conduct): add code of conduct May 15, 2017
CONTRIBUTING.md docs: add some info about releasing in contributing guidelines Oct 19, 2017
LICENSE chore: update license May 7, 2017
README.md feat: support symbol id interpolator as function May 26, 2018
karma.conf.js Add runtime deps & compile configs Apr 15, 2017
npm-shrinkwrap.json ci(codeclimate): add npm shrinkwrap for node security analysis May 8, 2017
package.json chore(release): 3.9.0 May 26, 2018
plugin.js Update package.json & add handy entry point for plugin Apr 23, 2017
wallaby-runtime.config.js Fix eslint issues Apr 24, 2017
wallaby.config.js Add runtime deps & compile configs Apr 15, 2017
webpack-runtime.config.js Refactoring Apr 28, 2017
yarn.lock chore(build): make possible to build examples with webpack 4 Mar 19, 2018

README.md

SVG sprite loader

NPM version Build status CodeClimate score Documentation score Dependencies status Dev dependencies status NPM downloads

Webpack loader for creating SVG sprites.

🎉 2.0 is out, please read the migration guide & overview.

⚠️ For old v0.x versions see the README in the v0 branch.

Table of contents

Why it's cool

  • Minimum initial configuration. Most of the options are configured automatically.
  • Runtime for browser. Sprites are rendered and injected in pages automatically, you just refer to images via <svg><use xlink:href="#id"></use></svg>.
  • Isomorphic runtime for node/browser. Can render sprites on server or in browser manually.
  • Customizable. Write/extend runtime module to implement custom sprite behaviour. Write/extend runtime generator to produce your own runtime, e.g. React component configured with imported symbol.
  • External sprite file is generated for images imported from css/scss/sass/less/styl/html (SVG stacking technique).

Installation

npm install svg-sprite-loader -D
# via yarn
yarn add svg-sprite-loader -D

Configuration

// webpack 1
{
  test: /\.svg$/,
  loader: 'svg-sprite-loader',
  query: { ... }
}

// webpack 1 multiple loaders
{
  test: /\.svg$/,
  loaders: [
    `svg-sprite-loader?${JSON.stringify({ ... })}`,
    'svg-fill-loader',
    'svgo-loader'
  ]
}

// webpack >= 2
{
  test: /\.svg$/,
  loader: 'svg-sprite-loader',
  options: { ... }
}

// webpack >= 2 multiple loaders
{
  test: /\.svg$/,
  use: [
    { loader: 'svg-sprite-loader', options: { ... } },
    'svg-fill-loader',
    'svgo-loader'
  ]
}

symbolId (string | function(path, query), default [name])

How <symbol> id attribute should be named. All patterns from loader-utils#interpolateName are supported. Also can be a function which accepts 2 args - file path and query string and return symbol id:

{
  symbolId: (path) => path.basename(path)
}

symbolRegExp (default '')

Passed to the symbolId interpolator to support the [N] pattern in the loader-utils name interpolator

esModule (default true, autoconfigured)

Generated export format:

  • when true loader will produce export default ....
  • when false the result is module.exports = ....

By default depends on used webpack version: true for webpack >= 2, false otherwise.

Runtime configuration

When you require an image, loader transforms it to SVG <symbol>, adds it to the special sprite storage and returns class instance that represents symbol. It contains id, viewBox and content (id, viewBox and url in extract mode) fields and can later be used for referencing the sprite image, e.g:

import twitterLogo from './logos/twitter.svg';
// twitterLogo === SpriteSymbol<id: string, viewBox: string, content: string>
// Extract mode: SpriteSymbol<id: string, viewBox: string, url: string, toString: Function>

const rendered = `
<svg viewBox="${twitterLogo.viewBox}">
  <use xlink:href="#${twitterLogo.id}" />
</svg>`;

When browser event DOMContentLoaded is fired, sprite will be automatically rendered and injected in the document.body. If custom behaviour is needed (e.g. a different mounting target) default sprite module could be overridden via spriteModule option. Check example below.

spriteModule (autoconfigured)

Path to sprite module that will be compiled and executed at runtime. By default it depends on target webpack config option:

  • svg-sprite-loader/runtime/browser-sprite.build for 'web' target.
  • svg-sprite-loader/runtime/sprite.build for other targets.

If you need custom behavior, use this option to specify a path of your sprite implementation module. Path will be resolved relative to the current webpack build folder, e.g. utils/sprite.js placed in current project dir should be written as ./utils/sprite.

Example of sprite with custom mounting target (copypasted from browser-sprite):

import BrowserSprite from 'svg-baker-runtime/src/browser-sprite';
import domready from 'domready';

const sprite = new BrowserSprite();
domready(() => sprite.mount('#my-custom-mounting-target'));

export default sprite; // don't forget to export!

It's highly recommended to extend default sprite classes:

symbolModule (autoconfigured)

Same as spriteModule, but for sprite symbol. By default also depends on target webpack config option:

  • svg-sprite-loader/runtime/browser-symbol.build for 'web' target.
  • svg-sprite-loader/runtime/symbol.build for other targets.

runtimeGenerator (default generator)

Path to node.js script that generates client runtime. Use this option if you need to produce your own runtime, e.g. React component configured with imported symbol. Example.

runtimeCompat (default false, deprecated)

Should runtime be compatible with earlier v0.x loader versions. This option will be removed in the next major version release.

runtimeOptions

Arbitrary data passed to runtime generator. Reserved for future use when other runtime generators will be created.

Extract configuration

In the extract mode loader should be configured with plugin, otherwise an error is thrown. Example:

// webpack.config.js
const SpriteLoaderPlugin = require('svg-sprite-loader/plugin');

...

{
  plugins: [
    new SpriteLoaderPlugin()
  ]
}

extract (default false, autoconfigured)

Switches loader to the extract mode. Enabled automatically for images imported from css/scss/sass/less/styl/html files.

spriteFilename (type string|Function<string>,default sprite.svg)

Filename of extracted sprite. Multiple sprites can be generated by specifying different loader rules restricted with include option or by providing custom function which recieves SVG file absolute path, e.g.:

{
  test: /\.svg$/,
  loader: 'svg-sprite-loader',
  options: {
    extract: true,
    spriteFilename: svgPath => `sprite${svgPath.substr(-4)}`
  }
}

[hash] in sprite filename will be replaced by it's content hash. It is also possible to generate sprite for each chunk by using [chunkname] pattern in spriteFilename option. This is experimental feature, use it with caution!

publicPath (type: string, default: __webpack_public_path__)

Custom public path for sprite file.

{
  test: /\.svg$/,
  loader: 'svg-sprite-loader',
  options: {
    extract: true,
    publicPath: '/'
  }
}

Plain sprite

You can render plain sprite in extract mode without styles and usages. Pass plainSprite: true option to plugin constructor:

{
  plugins: [
    new SpriteLoaderPlugin({ plainSprite: true })
  ]
}

Sprite attributes

Sprite <svg> tag attributes can be specified via spriteAttrs plugin option:

{
  plugins: [
    new SpriteLoaderPlugin({
      plainSprite: true,
      spriteAttrs: {
        id: 'my-custom-sprite-id'
      }
    })
  ]
}

Examples

See examples folder.

Contributing guidelines

See CONTRIBUTING.md.

License

See LICENSE

Credits

Huge thanks for all this people.