react-svg

react-svg

A React component that injects SVG into the DOM.

Background | Basic Usage | Live Examples | API | Installation | FAQ | License

Background

This component uses @tanem/svg-injector to fetch an SVG from a given URL and inject its markup into the DOM (why?). Fetched SVGs are cached, so multiple uses of the same SVG only require a single request.

Basic Usage

import { createRoot } from 'react-dom/client'
import { ReactSVG } from 'react-svg'

const container = document.getElementById('root')
const root = createRoot(container)
root.render(<ReactSVG src="svg.svg" />)

Live Examples

• Accessibility: Source | Sandbox
• API Usage: Source | Sandbox
• Basic Usage: Source | Sandbox
• Before Injection: Source | Sandbox
• CSS Animation: Source | Sandbox
• CSS-in-JS: Source | Sandbox
• Data URL: Source | Sandbox
• External Stylesheet: Source | Sandbox
• Fallbacks: Source | Sandbox
• Iframe: Source | Sandbox
• Loading: Source | Sandbox
• No Extension: Source | Sandbox
• Sprite Usage: Source | Sandbox
• SSR: Source | Sandbox
• Styled Components: Source | Sandbox
• SVG Wrapper: Source | Sandbox
• Typescript: Source | Sandbox
• UMD Build (Development): Source | Sandbox
• UMD Build (Production): Source | Sandbox

API

Props

• src - The SVG URL. Supports fetchable URLs (relative or absolute), data:image/svg+xml URLs (URL-encoded or base64), and SVG sprite sheets via fragment identifiers (e.g. sprite.svg#icon-star). See the data URL example and sprite usage example.
• afterInjection(svg) - Optional Function to call after the SVG is injected. svg is the injected SVG DOM element. If an error occurs during execution it will be routed to the onError callback, and if a fallback is specified it will be rendered. Defaults to () => {}.
• beforeInjection(svg) - Optional Function to call just before the SVG is injected. svg is the SVG DOM element which is about to be injected. If an error occurs during execution it will be routed to the onError callback, and if a fallback is specified it will be rendered. Defaults to () => {}.
• desc - Optional String used for SVG <desc> element content. If a <desc> exists it will be replaced, otherwise a new <desc> is created. When set, a unique id is added to the <desc> element and aria-describedby is set on the SVG for assistive technology. Defaults to '', which is a noop.
• evalScripts - Optional Run any script blocks found in the SVG. One of 'always', 'once', or 'never'. Defaults to 'never'.
• fallback - Optional Fallback to use if an error occurs during injection, or if errors are thrown from the beforeInjection or afterInjection functions. Can be a string, class component, or function component. Defaults to null.
• httpRequestWithCredentials - Optional Boolean indicating if cross-site Access-Control requests for the SVG should be made using credentials. Defaults to false.
• loading - Optional Component to use during loading. Can be a string, class component, or function component. Defaults to null.
• onError(error) - Optional Function to call if an error occurs during injection, or if errors are thrown from the beforeInjection or afterInjection functions. error is an unknown object. Defaults to () => {}.
• renumerateIRIElements - Optional Boolean indicating if SVG IRI addressable elements should be renumerated. Defaults to true. When enabled, IDs on IRI-addressable elements (clipPath, linearGradient, mask, path, etc.) are made unique, and all references to them (presentation attributes, href/xlink:href, inline style attributes, and <style> element text) are updated. Note: all matching element types are renumerated, not only those inside <defs>. Set to false if you need to query injected elements by their original IDs.
• title - Optional String used for SVG <title> element content. If a <title> exists it will be replaced, otherwise a new <title> is created. When set, a unique id is added to the <title> element and aria-labelledby is set on the SVG for assistive technology. Defaults to '', which is a noop.
• useRequestCache - Optional Use SVG request cache. Defaults to true.
• wrapper - Optional Wrapper element types. One of 'div', 'span' or 'svg'. Defaults to 'div'.

Other non-documented properties are applied to the outermost wrapper element.

Example

<ReactSVG
  afterInjection={(svg) => {
    console.log(svg)
  }}
  beforeInjection={(svg) => {
    svg.classList.add('svg-class-name')
    svg.setAttribute('style', 'width: 200px')
  }}
  className="wrapper-class-name"
  desc="Description"
  evalScripts="always"
  fallback={() => <span>Error!</span>}
  httpRequestWithCredentials={true}
  loading={() => <span>Loading</span>}
  onClick={() => {
    console.log('wrapper onClick')
  }}
  onError={(error) => {
    console.error(error)
  }}
  renumerateIRIElements={false}
  src="svg.svg"
  title="Title"
  useRequestCache={false}
  wrapper="span"
/>

Installation

$ npm install react-svg

UMD builds are also available for use with pre-React 19 via unpkg:

• https://unpkg.com/react-svg/dist/react-svg.umd.development.js
• https://unpkg.com/react-svg/dist/react-svg.umd.production.js

For the non-minified development version, make sure you have already included:

• React
• ReactDOM
• PropTypes

For the minified production version, make sure you have already included:

• React
• ReactDOM

FAQ

Why are there two wrapping elements?

This module delegates its core behaviour to @tanem/svg-injector, which requires a parent node when swapping in the SVG element. The swap occurs outside of React flow, so we don't want React updates to conflict with the DOM nodes @tanem/svg-injector is managing.

Example output, assuming a div wrapper:

<div> <!-- The wrapper, managed by React -->
  <div> <!-- The parent node, managed by @tanem/svg-injector -->
    <svg>...</svg> <!-- The swapped-in SVG, managed by @tanem/svg-injector -->
  </div>
</div>

See:

• Integrating with Other Libraries.

Related issues and PRs:

• #24.
• #30.
• #36.
• #48.

Can I use data URIs or inline SVG strings?

data:image/svg+xml URLs are supported (both URL-encoded and base64-encoded). The underlying library parses the SVG content directly from the data URL using DOMParser, without making a network request. This is useful when bundlers like Vite inline small SVGs as data URIs. See the data URL example for details.

Inline SVG strings (raw markup passed directly as the src prop) are not supported. If you already have the SVG markup as a string (for example, a dynamically generated chart), consider parsing it with DOMParser and appending the result yourself, or rendering it with dangerouslySetInnerHTML. These approaches avoid the fetch step entirely and will also avoid the brief flash that occurs when react-svg re-injects on src change.

Security note: inserting SVG strings into the DOM bypasses React's built-in sanitisation and can expose your application to XSS if the content is not trusted. If the SVG originates from user input or a third party, sanitise it first with a library like DOMPurify before inserting it into the page.

License

MIT

Similar packages

Other packages similar to react-svg

react-inlinesvg

react-inlinesvg is a React component that allows you to load and inline SVGs. It provides similar functionality to react-svg but focuses on inlining SVGs directly into the DOM, which can be useful for applying CSS styles directly to the SVG elements.

svgr

SVGR is a tool that transforms SVGs into React components. It allows you to import SVG files as React components, providing a more integrated approach to using SVGs in React applications. Unlike react-svg, SVGR converts SVG files into React components at build time.

react-svg-loader

react-svg-loader is a Webpack loader that allows you to import SVG files as React components. It provides a similar functionality to SVGR but is specifically designed to work with Webpack. This package is useful if you are already using Webpack in your build process.