svg-react-loader

What is svg-react-loader?

The svg-react-loader npm package is a Webpack loader that allows you to import SVG files as React components. This enables you to use SVGs in your React applications with ease, providing the ability to manipulate them using React's props and state.

What are svg-react-loader's main functionalities?

Importing SVG as React Component

This feature allows you to import an SVG file and use it as a React component. You can then manipulate the SVG using standard React props such as width, height, and fill.

import MyIcon from './my-icon.svg';

const App = () => (
  <div>
    <MyIcon width={50} height={50} fill="blue" />
  </div>
);

export default App;

Customizing SVG with Props

This feature demonstrates how you can pass custom props to the imported SVG component, such as className and style, to further customize its appearance.

import MyIcon from './my-icon.svg';

const App = () => (
  <div>
    <MyIcon className="custom-class" style={{ fill: 'red' }} />
  </div>
);

export default App;

Using SVGs in JSX

This feature shows how you can seamlessly integrate SVG components into your JSX, making it easy to include icons and other SVG graphics in your React components.

import MyIcon from './my-icon.svg';

const App = () => (
  <div>
    <h1>Welcome to My App</h1>
    <MyIcon />
  </div>
);

export default App;

Other packages similar to svg-react-loader

react-svg

The react-svg package allows you to import SVG files and use them as React components. It provides similar functionality to svg-react-loader but is more focused on providing a higher-level API for working with SVGs in React.

svgr

SVGR is a tool that transforms SVGs into React components. It offers a CLI, webpack loader, and a Node.js API, making it a versatile option for integrating SVGs into React applications. Compared to svg-react-loader, SVGR provides more customization options and can be used outside of a Webpack context.

react-inlinesvg

The react-inlinesvg package allows you to load SVGs inline in your React components. It provides a simple API for fetching and rendering SVGs, and it supports features like caching and fallback content. This package is more focused on inline SVG rendering compared to svg-react-loader.

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 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 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. 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):

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

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. 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

// 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

// 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:

{
    "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 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 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 for some examples.

Report an Issue

• Bugs
• Contact the author: [e-mail]

License

MIT