react-svg
TypeScript icon, indicating that this package has built-in type declarations

16.3.0 • Public • Published

react-svg

npm version build status coverage status npm downloads minzipped size

A React component that injects SVG into the DOM.

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

Background

Let's say you have an SVG available at some URL, and you'd like to inject it into the DOM for various reasons. This module does the heavy lifting for you by delegating the process to @tanem/svg-injector, which makes an AJAX request for the SVG and then swaps in the SVG markup inline. The async loaded SVG is also cached, so multiple uses of an SVG only require a single server 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

API

Props

  • src - The SVG URL.
  • 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. 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.
  • title - Optional String used for SVG <title> element content. If a <title> exists it will be replaced, otherwise a new <title> is created. 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

⚠️This library depends on @tanem/svg-injector, which uses Array.from(). If you're targeting browsers that don't support that method, you'll need to ensure an appropriate polyfill is included manually. See this issue comment for further detail.

$ npm install react-svg

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

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

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

FAQ

Why are there two wrapping elements?

This module delegates it's core behaviour to @tanem/svg-injector, which requires the presence of a parent node when swapping in the SVG element. The swapping in 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:

Related issues and PRs:

License

MIT

Versions

Current Tags

VersionDownloads (Last 7 Days)Tag
14.0.0-beta.10beta
16.3.035,120latest

Version History

VersionDownloads (Last 7 Days)Published
16.3.035,120
16.2.014,406
16.1.3435,755
16.1.333,571
16.1.322,203
16.1.31746
16.1.30426
16.1.291,445
16.1.28420
16.1.27838
16.1.2664
16.1.25167
16.1.24121
16.1.23233
16.1.22435
16.1.2154
16.1.2049
16.1.191,446
16.1.18931
16.1.17433
16.1.1684
16.1.15466
16.1.14145
16.1.1312
16.1.12530
16.1.11209
16.1.10191
16.1.911
16.1.866
16.1.7614
16.1.6725
16.1.535
16.1.437
16.1.21,224
16.1.1179
16.1.068
16.0.077
15.1.2115,964
15.1.203
15.1.197
15.1.18112
15.1.1795
15.1.1630
15.1.15178
15.1.14153
15.1.130
15.1.1265
15.1.11136
15.1.10369
15.1.9102
15.1.891
15.1.776
15.1.6805
15.1.534
15.1.420
15.1.31,296
15.1.233
15.1.111
15.1.01,682
15.0.434
15.0.319
15.0.2192
15.0.1185
15.0.030
14.1.1910,038
14.1.18799
14.1.1787
14.1.16300
14.1.1515
14.1.1429
14.1.1339
14.1.12168
14.1.113
14.1.1084
14.1.931
14.1.830
14.1.734
14.1.6109
14.1.581
14.1.41,283
14.1.317
14.1.220
14.1.1245
14.1.05
14.0.173,167
14.0.1621
14.0.1517
14.0.140
14.0.1323
14.0.122
14.0.11240
14.0.1030
14.0.953
14.0.89
14.0.750
14.0.612
14.0.530
14.0.4374
14.0.3466
14.0.2277
14.0.18
14.0.00
14.0.0-beta.10
14.0.0-beta.00
13.0.61,769
13.0.530
13.0.426
13.0.3213
13.0.20
13.0.14
13.0.00
12.1.0533
12.0.10
12.0.01
11.2.55,483
11.2.46
11.2.360
11.2.257
11.2.119
11.2.00
11.1.4-beta.10
11.1.4-beta.00
11.1.4157
11.1.3142
11.1.25
11.1.118
11.1.027
11.0.44574
11.0.433
11.0.4267
11.0.4125
11.0.402
11.0.399
11.0.385
11.0.379
11.0.360
11.0.352
11.0.3418
11.0.338
11.0.321
11.0.310
11.0.306
11.0.295
11.0.2819
11.0.2715
11.0.262
11.0.251
11.0.240
11.0.2314
11.0.222
11.0.2115
11.0.202
11.0.191
11.0.1818
11.0.170
11.0.1630
11.0.151,718
11.0.142
11.0.13129
11.0.120
11.0.111
11.0.109
11.0.914
11.0.80
11.0.712
11.0.66
11.0.512
11.0.43
11.0.30
11.0.20
11.0.10
11.0.00
10.0.262,529
10.0.255
10.0.240
10.0.231,224
10.0.220
10.0.2176
10.0.204
10.0.1927
10.0.180
10.0.171
10.0.160
10.0.150
10.0.1456
10.0.134
10.0.120
10.0.110
10.0.1047
10.0.95
10.0.82
10.0.735
10.0.60
10.0.518
10.0.41
10.0.32
10.0.22
10.0.10
10.0.00
9.0.42,711
9.0.30
9.0.229
9.0.11
9.0.00
8.0.8300
8.0.7126
8.0.610
8.0.50
8.0.40
8.0.30
8.0.24
8.0.10
8.0.016
7.2.14856
7.2.130
7.2.120
7.2.110
7.2.100
7.2.90
7.2.81
7.2.73
7.2.646
7.2.50
7.2.40
7.2.31
7.2.228
7.2.10
7.2.014
7.1.10
7.1.00
7.0.10
7.0.00
6.0.24347
6.0.230
6.0.220
6.0.210
6.0.20165
6.0.190
6.0.181
6.0.170
6.0.160
6.0.152
6.0.140
6.0.138
6.0.120
6.0.110
6.0.100
6.0.90
6.0.84
6.0.70
6.0.60
6.0.50
6.0.40
6.0.30
6.0.20
6.0.10
6.0.00
5.0.234,565
5.0.224
5.0.210
5.0.200
5.0.190
5.0.180
5.0.170
5.0.160
5.0.150
5.0.140
5.0.130
5.0.120
5.0.110
5.0.100
5.0.90
5.0.80
5.0.70
5.0.65
5.0.50
5.0.40
5.0.35
5.0.20
5.0.10
5.0.00
4.1.8246
4.1.70
4.1.60
4.1.50
4.1.40
4.1.34
4.1.20
4.1.10
4.1.00
4.0.178
4.0.160
4.0.150
4.0.140
4.0.132
4.0.120
4.0.110
4.0.100
4.0.90
4.0.80
4.0.70
4.0.60
4.0.50
4.0.41
4.0.30
4.0.20
4.0.10
4.0.00
3.0.694
3.0.50
3.0.40
3.0.30
3.0.22
3.0.11
3.0.00
2.2.181,700
2.2.173
2.2.160
2.2.150
2.2.140
2.2.131
2.2.121
2.2.113
2.2.108
2.2.90
2.2.80
2.2.70
2.2.65
2.2.50
2.2.41
2.2.30
2.2.20
2.2.10
2.2.00
2.1.221
2.1.2111
2.1.200
2.1.190
2.1.180
2.1.17627
2.1.160
2.1.150
2.1.140
2.1.130
2.1.120
2.1.110
2.1.100
2.1.90
2.1.80
2.1.70
2.1.60
2.1.50
2.1.40
2.1.30
2.1.20
2.1.10
2.1.00
2.0.21
2.0.10
2.0.00
1.1.514
1.1.40
1.1.30
1.1.20
1.1.10
1.1.00
1.0.00

Package Sidebar

Install

npm i react-svg

Weekly Downloads

170,787

Version

16.3.0

License

MIT

Unpacked Size

263 kB

Total Files

19

Last publish

Collaborators

  • tanem