# svg-react-loader

> A Webpack Loader to turn SVGs into React Components

Latest version **0.4.6** (published 2018-10-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install svg-react-loader
pnpm add svg-react-loader
yarn add svg-react-loader
bun add svg-react-loader
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.6 |
| Published | 2018-10-15 |
| First published | 2015-08-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 28.6 KB |
| Known vulnerabilities | 0 (+4 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 559 |
| Author | Jerry Hamlet |
| Maintainers | jhamlet |
| Keywords | webpack, loader, react, svg, component |

## Links

- npm: https://www.npmjs.com/package/svg-react-loader
- Repository: https://github.com/jhamlet/svg-react-loader
- Homepage: https://github.com/jhamlet/svg-react-loader#readme
- Issues: https://github.com/jhamlet/svg-react-loader/issues
- npm.io page: https://npm.io/package/svg-react-loader

## Dependencies (6)

- [rx](https://npm.io/package/rx.md) 4.1.0
- [css](https://npm.io/package/css.md) 2.2.4
- [ramda](https://npm.io/package/ramda.md) 0.21.0
- [xml2js](https://npm.io/package/xml2js.md) 0.4.17
- [traverse](https://npm.io/package/traverse.md) 0.6.6
- [loader-utils](https://npm.io/package/loader-utils.md) 1.1.0

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.4.6 (latest) — 2018-10-15
- 0.4.0-beta.2 (next) — 2016-07-31
- 0.4.0-beta.1 (unstable) — 2016-07-30
- 0.4.5 — 2017-08-26
- 0.4.4 — 2017-06-27
- 0.4.3 — 2017-06-15
- 0.4.2 — 2017-06-15
- 0.4.1 — 2017-06-15
- 0.4.0 — 2017-06-15
- 0.3.7 — 2016-07-31
- 0.3.6 — 2016-07-19
- 0.3.5 — 2016-06-01
- 0.3.3 — 2016-03-02
- 0.3.2 — 2015-12-07
- 0.3.1 — 2015-11-03
- … 9 more at https://npm.io/package/svg-react-loader/versions

## README

SVG to React Loader
===================

> A Webpack Loader to turn SVGs into React Components

Summary
-------

A webpack loader allowing for inline usage of a SVG as a React component, or for
composing individual SVGs into larger ones.

The latest version has been refactored to allow for receiving an SVG/XML string
or an JSON [object-tree](#object-tree-api) representing an SVG. This allows for
other loaders before `svg-react` to alter/update/remove nodes before reaching
`svg-react`.

In addition, the new [filters](#filters) API allows for additional ways to
modify the generated SVG Component. This allows `svg-react` to also be used as a
pre-loader (with `filters` and `raw=true` params) for modifying SVGs before they
are acted on by the loader version of `svg-react`.

### Notes

> As of version 0.4.0, `svg-react-loader` no longer requires `babel` to
> transpile the generated code. Everything is returned as an ES5-7 compatible
> module, and the component is just a
> [function](https://facebook.github.io/react/docs/reusable-components.html#stateless-functions).
> With that, it only works with React@>=0.14


Installation
------------

~~~
% npm install --save-dev svg-react-loader
~~~


Usage
-----

ES6+ (Assuming a `babel-loader` is used on `/\.jsx?$/` files):

~~~js
import React, { Component } from 'react';
import Icon from 'svg-react-loader?name=Icon!../svg/my-icon.svg';

export default class MyIcon extends Component {
    render () {
        return <Icon className='normal' />;
    }
};
~~~

ES5

~~~js
var React = require('react');
var Icon = require('svg-react-loader?name=Icon!../svg/my-icon.svg');

module.exports = React.createClass({
    render () {
        return React.createElement(Icon, { className: 'normal' });
    }
});
~~~


Documentation
-------------

### Query Params

Query params can be used on the loader path, or on the resource's path. Those on
the resource will override those given for the loader.

* `name`: `displayName` to use for the compiled component. Defaults to using the
  resource's file name, capitalized and camelCased. ex. `"?name=MyIcon"`

* `tag`: Override the root-level tag name.

* `props`: Attributes to apply to the root-level tag. If a certain attribute is
  already assigned to the tag, the value here will override that.

* `attrs`: Alias for `props`

* `filters`: If given on the query string, it is a list of module names, or
  filepaths, to load as [filter functions](#filters). If given in the webpack
  config as a `svgReactLoader.filters`, or as `query.filters` for the loader
  configuration object, it is an array of functions.

* `classIdPrefix`: A string to prefix all class or id selectors in found style
  blocks, or within `className` properties, with. If indicated without a string,
  the file's basename will be used as a prefix.

* `raw`: If set to `true` will output the parsed object tree repesenting the SVG
  as a JSON string. Otherwise, returns a string of JavaScript that represents
  the component's module.

* `propsMap`: If given on the query string, it is an array of colon separated
  `propname:translatedname` pairs. If given in the webpack configuration as
  `svgReactLoader.propsMap`, or in an object query for the loader configuration,
  is a simple object of `propname: 'translatedname'`

* `xmlnsTest`: A regular expression used to remove non-supported xmlns
  attributes. Default is `/^xmlns(Xlink)?$/`

* `titleCaseDelim`: A regular expression used to generate component's name. It
  would be ignore if `name` was set.
  Default is `/[._-]/`

### Examples
#### Webpack 1

~~~js
// webpack configuration
module: {
    loaders: [
        {
            test: /\.svg$/,
            exclude: /node_modules/,
            loader: 'svg-react-loader',
            query: {
                classIdPrefix: '[name]-[hash:8]__',
                filters: [
                    function (value) {
                        // ...
                        this.update(newvalue);
                    }
                ],
                propsMap: {
                    fillRule: 'fill-rule',
                    foo: 'bar'
                },
                xmlnsTest: /^xmlns.*$/
            }
        }
    ]
}

// Resource paths
import MyIcon from 'svg-react-loader?name=MyIcon!../svg/icon.svg';
import MyIcon from 'svg-react-loader?tag=symbol!../svg/icon.svg';
import MyIcon from 'svg-react-loader?tag=symbol&props[]=id:my-icon?../svg/icon.svg';
import MyIcon from 'svg-react-loader?filters[]=./my-filter.js!../svg/icon.svg';
~~~

#### Webpack 2-3

~~~js
// webpack configuration
module: {
    loaders: [
        {
            test: /\.svg$/,
            exclude: /node_modules/,
            use: {
                loader: 'svg-react-loader',
                options: {
                    tag: 'symbol',
                    attrs: {
                        title: 'example',
                    },
                    name: 'MyIcon',
                },
            },
        }
    ]
}

// Resource paths
import MyIcon from '../svg/icon.svg';
~~~

### Object Tree API

Internally, `svg-react-loader` converts the given SVG/XML into an object tree
that looks something like:

~~~js
{
    "tagname": "svg",
    "props": {
        "xmlns": "http://www.w3.org/2000/svg",
        "xmlns:xlink": "http://www.w3.org/1999/xlink",
        "viewBox": "0 0 16 16",
        "enable-background": "new 0 0 16 16",
        "xml:space": "preserve"
    },
    "children": [
        {
            "tagname": "rect",
            "props": {
                "x": "0",
                "y": "0",
                "width": "16",
                "height": "16",
                "fill": "#fff"
            }
        },
        {
            "tagname": "text",
            "children": ["Foobar"]
        }
    ]
}
~~~

It then uses a variety of [filters](#filters) to modify the tree to conform to
how `React` expects to see props, styles, etc...

If `svg-react-loader` receives a JSON string instead of string of SVG/XML, it
expects to receive it in the above format (i.e.: objects with properties
'tagname', 'props', and 'children'). Children is always an array (unless empty),
and children can be objects with the mentioned props, or a plain string (for
text nodes).

### Filters

A filter is just a function that accepts one value, and it has the same `this`
context as the [traverse](https://www.npmjs.com/package/traverse) API.

`svg-react-loader` is really just a series of filters applied to a parsed
SVG/XML, or JSON, string and then regenerated as a string to form a React
functional component.

Review [lib/sanitize/filters](lib/sanitize/filters) for some examples.

Report an Issue
---------------

* [Bugs](http://github.com/jhamlet/svg-react-loader/issues)
* Contact the author: <jerry@hamletink.com>


License
-------

[MIT](./LICENSE)

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