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.

📱 If you also want to use SVG images for your application launcher icons, you might want to check out react-native-svg-app-icon.

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 (i.e. metro version 0.44) or later to work.

To enable the asset plugin you will need to include it in the metro configuration.

For expo projects you will first need to enable customization of the metro config:

npx expo customize metro.config.js

Then, in the metro.config.js file, add 'react-native-svg-asset-plugin' to the transformer asset plugins like this:

config.transformer.assetPlugins.push('react-native-svg-asset-plugin');

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: true,
      },
    }),
    assetPlugins: ['react-native-svg-asset-plugin'],
  },
};

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.

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:

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

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

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.