Registry /
web-framework / gatsby-plugin-react-svg
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
plugin (default config)
✓ {
resolve: 'gatsby-plugin-react-svg',
options: {
rule: {
include: /assets/
}
}
}
✗ plugins: ['gatsby-plugin-react-svg']
Without rule.include/exclude, the plugin does nothing and may cause conflicts with url-loader. Always specify include or exclude.
SVG React component
✓ import Icon from './path/assets/icon.svg'; // renders as <Icon />
✗ const Icon = require('./path/assets/icon.svg');
SVG import as default export works only with ESM. CommonJS require may return a string URL instead of a component.
TypeScript declaration
✓ declare module '*.svg' {
const content: any;
export default content;
}
✗ export = content;
Use 'export default' to match the ESM default import pattern. export = breaks with strict ESM.
Inline SVG import (explicit loader)
✓ import Icon from '-!svg-react-loader?props[]=className:w-4 h-4!../icons/Fork.inline.svg';
✗ import Icon from 'svg-react-loader!../icons/Fork.inline.svg';
Prefix with '-!' to disable other loaders (e.g., url-loader). Without '-!', Gatsby may apply multiple loaders and cause errors.
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;
Errors
Common errors & fixes
InvalidCharacterError: Failed to execute 'createElement' on 'Document': The tag name provided ('data:image/svg+xml; ...
SVG is being processed by url-loader instead of svg-react-loader, resulting in a data URI string used as a tag name.
fixAdd rule.include matching your SVG paths (e.g., include: /\.inline\.svg$/) so the plugin correctly excludes them from url-loader.
Error: The plugin "gatsby-plugin-react-svg" resolved instead of "gatsby-plugin-react-svg"
Plugin name typo or incorrect package location.
fixEnsure the plugin is installed: npm install gatsby-plugin-react-svg, and the name in gatsby-config matches exactly 'gatsby-plugin-react-svg'.
WebpackError: Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type.
SVG file is not being handled by any loader; plugin may not be configured or webpack rule is incorrect.
fixVerify plugin is listed in gatsby-config with proper rule.include/include directory. Restart gatsby develop.
Audit
Dependencies
gatsbyrequiredPeer dependency; plugin hooks into Gatsby's webpack config