gatsby-plugin-react-svg

3.3.0 verified Sat Apr 25 auth: no javascript

A Gatsby plugin that integrates svg-react-loader into the webpack configuration, enabling import of SVG files as React components. Version 3.3.0 supports Gatsby v2 through v5. It automatically handles exclusion of SVG rules from the default url-loader when include/exclude patterns are specified. Differentiators include support for custom webpack rule options, SVG prop filtering via omitKeys, and compatibility with both inline SVG imports for React and regular SVG imports for CSS. Maintained with moderate release cadence.

Common errors

error InvalidCharacterError: Failed to execute 'createElement' on 'Document': The tag name provided ('data:image/svg+xml; ... ↓

cause SVG is being processed by url-loader instead of svg-react-loader, resulting in a data URI string used as a tag name.

fix

Add rule.include matching your SVG paths (e.g., include: /\.inline\.svg$/) so the plugin correctly excludes them from url-loader.

error Error: The plugin "gatsby-plugin-react-svg" resolved instead of "gatsby-plugin-react-svg" ↓

cause Plugin name typo or incorrect package location.

fix

Ensure the plugin is installed: npm install gatsby-plugin-react-svg, and the name in gatsby-config matches exactly 'gatsby-plugin-react-svg'.

error WebpackError: Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause SVG file is not being handled by any loader; plugin may not be configured or webpack rule is incorrect.

fix

Verify plugin is listed in gatsby-config with proper rule.include/include directory. Restart gatsby develop.

Warnings

breaking Without rule.include or rule.exclude, the plugin removes SVGs from url-loader entirely, breaking background-image and other CSS imports. ↓

fix Always specify rule.include or rule.exclude. Common pattern: include: /\.inline\.svg$/.

deprecated The omitKeys option is a simple filter but may be removed in future versions in favor of full filter functions. ↓

fix Prefer using the filters array with custom logic if you need more control.

gotcha Using require() to import SVGs returns a string (URL), not a React component. CJS require does not go through svg-react-loader. ↓

fix Use ESM import statements for SVG component imports.

gotcha If rule.include and rule.exclude are both omitted, the plugin does nothing but still runs, potentially causing confusion. ↓

fix Remove the plugin from gatsby-config if you do not intend to use it, or add proper rule options.

Install

npm install gatsby-plugin-react-svg

yarn add gatsby-plugin-react-svg

pnpm add gatsby-plugin-react-svg

Imports

plugin (default config)

wrong

plugins: ['gatsby-plugin-react-svg']

correct

{
  resolve: 'gatsby-plugin-react-svg',
  options: {
    rule: {
      include: /assets/
    }
  }
}

Without rule.include/exclude, the plugin does nothing and may cause conflicts with url-loader. Always specify include or exclude.

SVG React component
wrong
```
const Icon = require('./path/assets/icon.svg');
```
correct
```
import Icon from './path/assets/icon.svg'; // renders as <Icon />
```
SVG import as default export works only with ESM. CommonJS require may return a string URL instead of a component.
TypeScript declaration
wrong
```
export = content;
```
correct
```
declare module '*.svg' {
  const content: any;
  export default content;
}
```
Use 'export default' to match the ESM default import pattern. export = breaks with strict ESM.
Inline SVG import (explicit loader)
wrong
```
import Icon from 'svg-react-loader!../icons/Fork.inline.svg';
```
correct
```
import Icon from '-!svg-react-loader?props[]=className:w-4 h-4!../icons/Fork.inline.svg';
```
Prefix with '-!' to disable other loaders (e.g., url-loader). Without '-!', Gatsby may apply multiple loaders and cause errors.

Quickstart

Configures plugin to import SVGs ending with .inline.svg as React components, with TypeScript usage example.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-react-svg',
      options: {
        rule: {
          include: /\.inline\.svg$/ // only SVGs ending with .inline.svg
        }
      }
    }
  ]
};

// src/components/Icon.inline.svg (example SVG file)
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" fill="blue"/></svg>

// src/components/MyIcon.tsx
import Icon from './Icon.inline.svg';
const MyIcon = () => <Icon className="w-6 h-6" />;
export default MyIcon;