Skip to content
Asset plugin for importing SVG images in React Native
JavaScript Objective-C Ruby Java Python
Branch: master
Clone or download
Latest commit a202d64 Jul 21, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
example Match configuration examples Jul 21, 2019
flow-typed Initial implementation Mar 18, 2019
integration_tests Add metro integration tests (#21) Jul 21, 2019
src Add plugin configuration options (#25) Jul 21, 2019
.flowconfig Add plugin configuration options (#25) Jul 21, 2019
.gitignore Initial implementation Mar 18, 2019
.prettierrc.json Initial implementation Mar 18, 2019
.travis.yml
LICENSE Initial implementation Mar 18, 2019
README.md Match configuration examples Jul 21, 2019
babel.config.js Fix support for old node versions Mar 18, 2019
package-lock.json 0.2.0 Jul 21, 2019
package.json 0.2.0 Jul 21, 2019

README.md

react-native-svg-asset-plugin

Build Status

Asset plugin for React Native which enables using SVGs with Image components. Works by generating PNGs during compile time, and passing them to the metro transformer.

Installation

npm

npm install --save-dev react-native-svg-asset-plugin

No dependencies outside of NPM. Uses sharp for SVG rasterization.

Requires React Native version 0.57 or later to work. Expo not supported, instead you might want to use react-native-svg-transformer.

metro

Add 'react-native-svg-asset-plugin' to the list of assetPlugins in your metro.config.js file under the transformer section.

For example;

module.exports = {
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: false,
      },
    }),
    assetPlugins: ['react-native-svg-asset-plugin'],
  },
};

Usage

Just require your SVG files directly into React Native Image and ImageBackground components. For example:

<Image source={require('./assets/image.svg')} />

Scaled PNGs will be generated under the subdirectory .png-cache alongside the SVG files, so you might want to add a .gitignore entry to exclude the cache directory from your code repo.

Configuration

You can configure the plugin behaviour through the optional svgAssetPlugin field in your metro.config.js file under the transformer section.

For example;

module.exports = {
  transformer: {
    // ...
    assetPlugins: ['react-native-svg-asset-plugin'],
    svgAssetPlugin: {
      pngCacheDir: '.png-cache',
      scales: [1, 2, 3],
      output: {
        compressionLevel: 9,
      },
    },
  },
};

Where the possible configuration values are:

Field Type Default Description
cacheDir string '.png-cache' Name of directory to store cached PNGs.
scales number[] [1, 2, 3] PNG image scales to generate for different screen densities.
output object {} Sharp PNG output options.

You will need to reset the bundler cache with react-native start --reset-cache for configuration changes to take effect for already generated images.

Comparison with react-native-svg

Most alternative ways of displaying SVG content in React Native apps are based on thereact-native-svg library, which provides runtime rendering of SVG images. react-native-svg-asset-plugin works differently by rasetrizing the vector images to PNGs during compile time, and using the native image rendering APIs.

react-native-svg react-native-svg-asset-plugin
Rasterization Runtime Compile time
Runtime dependencies JS + Native None
Image compatibility No Yes
Remote assets Yes No
App size Smaller Larger

Technical details

The plugin works by intercepting loaded SVG assets, and transforming them to PNGs before they are loaded by the metro transformer. After being loaded by the transformer, they work as any other PNG file in React Native, meaning you can use and style them freely in Image components.

Each SVG file produces three PNG files in 1x, 2x and 3x scales. The size of the PNG images are defined by the width and height attributes of the SVG images.

SVGs are rasterized to PNGs using the sharp Node.js library, which is based on libvips C library, which includes the librsvg library that renders the SVG images.

You can’t perform that action at this time.