{"id":20051,"library":"gatsby-plugin-react-svg","title":"gatsby-plugin-react-svg","description":"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.","status":"active","version":"3.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/jacobmischka/gatsby-plugin-react-svg","tags":["javascript","gatsby","svg","react","gatsby-plugin"],"install":[{"cmd":"npm install gatsby-plugin-react-svg","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-plugin-react-svg","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-plugin-react-svg","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; plugin hooks into Gatsby's webpack config","package":"gatsby","optional":false}],"imports":[{"note":"Without rule.include/exclude, the plugin does nothing and may cause conflicts with url-loader. Always specify include or exclude.","wrong":"plugins: ['gatsby-plugin-react-svg']","symbol":"plugin (default config)","correct":"{\n  resolve: 'gatsby-plugin-react-svg',\n  options: {\n    rule: {\n      include: /assets/\n    }\n  }\n}"},{"note":"SVG import as default export works only with ESM. CommonJS require may return a string URL instead of a component.","wrong":"const Icon = require('./path/assets/icon.svg');","symbol":"SVG React component","correct":"import Icon from './path/assets/icon.svg'; // renders as <Icon />"},{"note":"Use 'export default' to match the ESM default import pattern. export = breaks with strict ESM.","wrong":"export = content;","symbol":"TypeScript declaration","correct":"declare module '*.svg' {\n  const content: any;\n  export default content;\n}"},{"note":"Prefix with '-!' to disable other loaders (e.g., url-loader). Without '-!', Gatsby may apply multiple loaders and cause errors.","wrong":"import Icon from 'svg-react-loader!../icons/Fork.inline.svg';","symbol":"Inline SVG import (explicit loader)","correct":"import Icon from '-!svg-react-loader?props[]=className:w-4 h-4!../icons/Fork.inline.svg';"}],"quickstart":{"code":"// gatsby-config.js\nmodule.exports = {\n  plugins: [\n    {\n      resolve: 'gatsby-plugin-react-svg',\n      options: {\n        rule: {\n          include: /\\.inline\\.svg$/ // only SVGs ending with .inline.svg\n        }\n      }\n    }\n  ]\n};\n\n// src/components/Icon.inline.svg (example SVG file)\n<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><circle cx=\"12\" cy=\"12\" r=\"10\" fill=\"blue\"/></svg>\n\n// src/components/MyIcon.tsx\nimport Icon from './Icon.inline.svg';\nconst MyIcon = () => <Icon className=\"w-6 h-6\" />;\nexport default MyIcon;","lang":"typescript","description":"Configures plugin to import SVGs ending with .inline.svg as React components, with TypeScript usage example."},"warnings":[{"fix":"Always specify rule.include or rule.exclude. Common pattern: include: /\\.inline\\.svg$/.","message":"Without rule.include or rule.exclude, the plugin removes SVGs from url-loader entirely, breaking background-image and other CSS imports.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Prefer using the filters array with custom logic if you need more control.","message":"The omitKeys option is a simple filter but may be removed in future versions in favor of full filter functions.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Use ESM import statements for SVG component imports.","message":"Using require() to import SVGs returns a string (URL), not a React component. CJS require does not go through svg-react-loader.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Remove the plugin from gatsby-config if you do not intend to use it, or add proper rule options.","message":"If rule.include and rule.exclude are both omitted, the plugin does nothing but still runs, potentially causing confusion.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Add rule.include matching your SVG paths (e.g., include: /\\.inline\\.svg$/) so the plugin correctly excludes them from url-loader.","cause":"SVG is being processed by url-loader instead of svg-react-loader, resulting in a data URI string used as a tag name.","error":"InvalidCharacterError: Failed to execute 'createElement' on 'Document': The tag name provided ('data:image/svg+xml; ..."},{"fix":"Ensure the plugin is installed: npm install gatsby-plugin-react-svg, and the name in gatsby-config matches exactly 'gatsby-plugin-react-svg'.","cause":"Plugin name typo or incorrect package location.","error":"Error: The plugin \"gatsby-plugin-react-svg\" resolved instead of \"gatsby-plugin-react-svg\""},{"fix":"Verify plugin is listed in gatsby-config with proper rule.include/include directory. Restart gatsby develop.","cause":"SVG file is not being handled by any loader; plugin may not be configured or webpack rule is incorrect.","error":"WebpackError: Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}