Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jhamlet/svg-react-loader

Webpack SVG to React Component Loader
https://github.com/jhamlet/svg-react-loader

Last synced: 30 days ago
JSON representation

Webpack SVG to React Component Loader

Lists

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 ;

    }

};

~~~



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: 



License

-------



[MIT](./LICENSE)