react-inlinesvg

What is react-inlinesvg?

The react-inlinesvg package allows you to easily include and manipulate SVG files directly within your React components. This can be useful for adding icons, illustrations, and other vector graphics to your application without the need for additional HTTP requests.

What are react-inlinesvg's main functionalities?

Basic SVG Inclusion

This feature allows you to include an SVG file directly in your React component by specifying the path to the SVG file.

import React from 'react';
import SVG from 'react-inlinesvg';

const App = () => (
  <div>
    <SVG src="/path/to/your.svg" />
  </div>
);

export default App;

Customizing SVG with Props

You can customize the SVG by passing additional props such as className or using the preProcessor function to modify the SVG code before it is rendered.

import React from 'react';
import SVG from 'react-inlinesvg';

const App = () => (
  <div>
    <SVG src="/path/to/your.svg" className="custom-class" preProcessor={(code) => code.replace(/fill=".*?"/g, 'fill="currentColor"')} />
  </div>
);

export default App;

Handling Load and Error Events

This feature allows you to handle load and error events when the SVG is being fetched and rendered, providing better control over the SVG loading process.

import React from 'react';
import SVG from 'react-inlinesvg';

const App = () => (
  <div>
    <SVG src="/path/to/your.svg" onLoad={() => console.log('SVG loaded!')} onError={(error) => console.error('Error loading SVG:', error)} />
  </div>
);

export default App;

Other packages similar to react-inlinesvg

react-svg

The react-svg package is another popular library for including SVGs in React applications. It provides similar functionality to react-inlinesvg, allowing you to load and manipulate SVG files. However, react-svg focuses more on ease of use and simplicity, while react-inlinesvg offers more customization options.

svg-react-loader

The svg-react-loader package is a Webpack loader that transforms SVG files into React components. This approach allows for more advanced manipulation and optimization of SVGs at build time, but it requires a more complex setup compared to react-inlinesvg.

react-svg-loader

The react-svg-loader package is similar to svg-react-loader but is specifically designed for use with React. It converts SVG files into React components, allowing for easy inclusion and manipulation of SVGs within your React application. It offers a balance between ease of use and customization.

README

react-inlinesvg

Load inline, local, or remote SVGs in your React components.

View the demo

Highlights

• 🏖 Easy to use: Just set the src
• 🛠 Flexible: Personalize the options to fit your needs
• ⚡️ Smart: Async requests will be cached.
• 🚀 SSR: Render a loader until the DOM is available
• 🟦 Typescript: Nicely typed

Usage

npm i react-inlinesvg

And import it into your code:

import React from 'react';
import SVG from 'react-inlinesvg';

export default function App() {
  return (
    <main>
      <SVG
        src="https://cdn.svgporn.com/logos/react.svg"
        width={128}
        height="auto"
        title="React"
      />
    </main>
  );
}

Props

src {string} - required.
The SVG file you want to load. It can be a require, URL, or a string (base64 or URL encoded). If you are using create-react-app and your file resides in the public directory, you can use the path directly without require.

baseURL {string}
An URL to prefix each ID in case you use the <base> tag and uniquifyIDs.

children {ReactNode}
The fallback content in case of a fetch error or unsupported browser.

<SVG src="...">
	<img src="..." alt="fallback" />
</SVG>

cacheRequests {boolean} ▶︎ true
Cache remote SVGs.
Starting in version 4.x, you can also cache the files permanently, read more below.

description {string}
A description for your SVG. It will override an existing <desc> tag.

fetchOptions {RequestInit}
Custom options for the request.

innerRef {React.Ref}
Set a ref in SVGElement.

The SVG is processed and parsed so the ref won't be set on the initial render. You can use the onLoad callback to get and use the ref instead.

loader {node}
A component to be shown while the SVG is loading.

onError {function}
A callback to be invoked if loading the SVG fails.
This will receive a single argument with:

• a FetchError with:

{
  message: string;
  type: string;
  errno: string;
  code: string;
}

• or an InlineSVGError, which has the following properties:

{
  name: 'InlineSVGError';
  data: object; // optional
  message: string;
}

onLoad {function}.
A callback to be invoked upon successful load.
This will receive 2 arguments: the src prop and an isCached boolean

preProcessor {function} ▶︎ string
A function to process the contents of the SVG text before parsing.

title {string | null}
A title for your SVG. It will override an existing <title> tag.
If null is passed, the <title> tag will be removed.

uniqueHash {string} ▶︎ a random 8 characters string [A-Za-z0-9]
A string to use with uniquifyIDs.

uniquifyIDs {boolean} ▶︎ false
Create unique IDs for each icon.

Any additional props will be passed down to the SVG element.

Example

<SVG
  baseURL="/home"
  cacheRequests={true}
  description="The React logo"
  loader={<span>Loading...</span>}
  onError={(error) => console.log(error.message)}
  onLoad={(src, isCached) => console.log(src, isCached)}
  preProcessor={(code) => code.replace(/fill=".*?"/g, 'fill="currentColor"')}
  src="https://cdn.svgporn.com/logos/react.svg"
  title="React"
  uniqueHash="a1f8d1"
  uniquifyIDs={true}
/>

Caching

You can use the browser's cache to store the SVGs permanently.
To set it up, wrap your app with the cache provider:

import { createRoot } from 'react-dom/client';
import CacheProvider from 'react-inlinesvg/provider';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <CacheProvider>
    <App />
  </CacheProvider>
);

Be aware of the limitations of the Cache API.

Browser Support

Any browsers that support inlining SVGs and fetch will work.

If you need to support legacy browsers, include a polyfill for fetch and Number.isNaN in your app. Take a look at react-app-polyfill or polyfill.io.

CORS

If you are loading remote SVGs, you must ensure it has CORS support.

Why do you need this package?

One of the reasons SVGs are awesome is that you can style them with CSS. Unfortunately, this is not useful in practice because the style element has to be in the same document. This leaves you with three bad options:

1. Embed the CSS in the SVG document
   • Can't use your CSS preprocessors (LESS, SASS)
   • Can't target parent elements (button hover, etc.)
   • Makes maintenance difficult
2. Link to a CSS file in your SVG document
   • Sharing styles with your HTML means duplicating paths across your project, making maintenance a pain
   • Not sharing styles with your HTML means extra HTTP requests (and likely duplicating paths between different SVGs)
   • Still can't target parent elements
   • Your SVG becomes coupled to your external stylesheet, complicating reuse.
3. Embed the SVG in your HTML
   • Bloats your HTML
   • SVGs can't be cached by browsers between pages.
   • A maintenance nightmare

But there's an alternative that sidesteps these issues: load the SVG with a GET request and then embed it in the document. This is what this component does.

Note

The SVG <use> element can be used to achieve something similar to this component. See this article for more information and this table for browser support and caveats.

Credits

Thanks to @matthewwithanm for creating this component and so kindly transferring it to me. I'll definitely keep up the good work! ❤️