Webpack loader to add/modify tags and attributes in SVG image. Main purpose - fill, stroke and other manipulations with image imported from CSS/SCSS/LESS/Stylus/PostCSS.

Package: svg-transform-loader

Created by: JetBrains

Last modified: Thu, 19 May 2022 03:40:34 GMT

Version: 2.0.13

License: MIT

Downloads: 51,813

Repository: https://github.com/JetBrains/svg-mixer

Install

npm install svg-transform-loader

yarn add svg-transform-loader

svg-transform-loader

Webpack loader to add/modify tags and attributes in SVG image. Main purpose -
fill, stroke and other manipulations with image imported from CSS/SCSS/LESS/Stylus/PostCSS.

Demo
Installation
Webpack config
Further SVG handling
How to pass transform parameters
Configuration
⚠Important notices

Demo

Fill image with white color:

 .img {
  background-image: url('./img.svg?fill=#fff');
}

Stroke image by using variable in SCSS:

 $stroke-color: #fff;

.img {
  background-image: url('./img.svg?stroke=#{$stroke-color}');
}

When used with postcss-move-props-to-bg-image-query
it is possible to specify transform parameters as usual CSS declarations:

 .img {
  background-image: url('./img.svg');
  -svg-fill: red;
  -svg-stroke: black;
}

Installation

npm install svg-transform-loader

Webpack config

It's safe to pass all SVGs through this loader, if no transform params presented
it just returns original source.

Transform parameters are passed via query string, so match rule for svg files
should consider this:

 module.exports = {
  module: {
    rules: [
      {
        test: /\.svg(\?.*)?$/, // match img.svg and img.svg?param=value
        use: [
          'url-loader', // or file-loader or svg-url-loader
          'svg-transform-loader'
        ]
      }
    ]
  }
}

Further SVG handling

Don't forget that this loader leaves any further SVG processing to your choice.
You can use:

url-loader/svg-url-loader to inline the SVG into CSS.
file-loader to save SVG as a file (read the notice).

How to pass transform parameters

Transform parameter has following syntax: attr_name=attr_value optional_selector.

Multiple values can be specified by separating them with comma: fill=red .path1, blue .path2.

Parameters can be combined: fill=red&stroke=black.

 .img {background-image: url('./img.svg?fill=#fff')}

/* Fill all <path/> tags */
.img {background-image: url('./img.svg?fill=#fff path')}

/* Fill all <path/> tags, stroke element with id="qwe" */
.img {background-image: url('./img.svg?fill=#fff path&stroke=black #qwe')}

Recommended: postcss-move-props-to-bg-image-query

It is possible to write parameters as usual style declarations in CSS and this
plugin will turn them into background image query params:

 .img {
  background-image: url('./img.svg');
  -svg-fill: #ffffff path, blue circle;
  -svg-stroke: #ede;
}

/* turns into */
.img {
  background-image: url('./img.svg?fill=%23ffffff%20path%2C%20blue%20circle&stroke=%23ede');
}

For more info read plugin docs.

Configuration

`raw`

Type: boolean

Default: true

By default loader returns transformed image as-is, which is convenient for further
processing with file-loader (e.g. to create a separate file), or
url-loader/svg-url-loader (to inline it in CSS code). However, sometimes you
might need to get the image as a module (like, for rendering with React). In this
case, you'll need to set raw: false.

`transformQuery`

TODO

⚠ Important notices

Usage with css-loader

Note that when using css-loader to handle CSS, sharp # symbol in image query
params should be encoded, because css-loader will treat it as
fragment identifier part of URL:

 .img {background-image: url(img.svg?fill=#f0f)}

/* will be treated as */
.img {background-image: url(img.svg?fill=)}

To work around this you have several options.

Recommended: use PostCSS plugin postcss-move-props-to-bg-image-query. See
more details in corresponding section.

Use special loader to encode sharp in CSS imports. svg-transform-loader comes
with special loader which can be used to encode sharp in CSS imports. This
loader should be defined before css-loader and after any other style
loaders (webpack call loaders from right to left). Please note that css-loader
importLoaders
option should be set to 1 or higher:

 // webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.svg(\?.*)?$/, 
        use: [
          'url-loader',
          'svg-transform-loader' 
        ]
      },
      {
        test: /\.scss$/,
        use: [
          {
            loader: 'css-loader',
            options: {
              importLoaders: 1 // This option should be set to work with encode-query loader
            }
          },
          'svg-transform-loader/encode-query', // loader should be defined BEFORE css-loader
          'sass-loader' // but AFTER any other loaders which produces CSS
        ]
      }
    ]
  }
}

Encode loader uses PostCSS under the hood, so if you already have it on
the project it's better to use postcss-move-props-to-bg-image-query
to avoid double parsing and performance downgrade.

Encode sharp manually. Replace # with %23 directly in import:
```
 .img {background-image: url(img.svg?fill=%23f0f)}
```

Use preprocessor mixin. If style preprocessor is used, sharp encoding can be
automated via mixin. Example of SCSS mixin:

 @mixin fill-background-image($url, $color) {
  $base-color: str-slice(inspect($color), 2);
  background-image: unquote('url("' + $url + "?fill=%23" + $base-color +'")');
}

/* and use it like this */
$hex-color: #e6e6e6;

.img {
  @include fill-background-image('img.svg', $hex-color);
}

Usage with resolve-url-loader

If you're using resolve-url-loader for rewriting paths in SCSS/LESS/etc, keep in
mind that it will remove query string by default and svg-transform-loader will
not be able to handle the image. To fix this set keepQuery resolve-url-loader
option to true:

 {
  test: /\.scss$/,
  use: [
    'css-loader',
    {
      loader: 'resolve-url-loader',
      options: {
        keepQuery: true // <- this!
      }
    },
    'sass-loader'
  ]
}