feat: support external SVG via Image tag by exoego · Pull Request #3281 · diegomura/react-pdf

exoego · 2026-01-21T14:51:51Z

Closes #1622
Closes #1250

Flow

Fetch the .svg image (base64 supported too)
Parse it as DOM using DOMParser in browser (or own parser in Node.js)
Convert the DOM into react-render <SVG> tag.

Other changes

During tests, I found some features are not working properly, so fixed those.
E.g. rx in rect, stop in gradient.

Attributions to SVG files

I've borrowed a complex SVG which is CC0 license (MIT license compatible) from this web page https://lukaszadam.com/illustrations
<style> tag in the file are converted to inline style since <SVG> seems not to support <style> yet.

Other SVG files are manually crafted.

Screenshot of example :

changeset-bot · 2026-01-21T14:51:55Z

🦋 Changeset detected

Latest commit: 02ab3e9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 8 packages

Name	Type
@react-pdf/vite-example	Minor
@react-pdf/layout	Minor
@react-pdf/render	Minor
@react-pdf/image	Minor
@react-pdf/renderer	Patch
@react-pdf/math	Patch
next-14	Patch
next-15	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

diegomura

@exoego amazing work! I appreciate this a lot.

I left some comments, most nit :) Let me know what you think about them, and feel free to push back on any. I think this is almost ready but I'd like to collect your thoughts on these points first

diegomura · 2026-04-11T09:34:42Z

    "@react-pdf/png-js": "^3.0.0",
-    "jay-peg": "^1.1.1"
+    "jay-peg": "^1.1.1",
+    "linkedom": "^0.18.12"


This lib is quite heavy. I generally try not to add more overhead. Is the rationale here that web (where bundle size is more important) won't need it and it's fine for Node?

Do we actually need a DOMParser polyfill here? Won't an xml to json solution be more lightweight + simplify the logic?

Btw, new math module has a parse svg logic, dependency free: https://github.com/diegomura/react-pdf/blob/master/packages/math/src/parseSvg.ts . We can extract it and reuse it maybe?

Although that does not have support for style tags and maybe other things a well. Maybe we can reuse your solution here there. I'd like to avoid duplicates

math's parseSvg seemingly does not support <!CDATA[ section, comment, single-quote attributes or maybe more.
So, added small parser de20194

Thanks. I'll extract and reuse that parser for math and other modules that require going from svg to react-pdf primitives

diegomura · 2026-04-11T09:36:25Z

+  // Use BROWSER constant to ensure this code is dead-code eliminated in browser build
+  if (!BROWSER) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const linkedom = require('linkedom');


I think it should be fine to just use import syntax. Rollup should be clever enough to strip it from the browser build.

This was fixed by replacing linkedom with own parser.

diegomura · 2026-04-11T09:42:16Z

+  key?: string;
+}
+
+export type AnyImage = Image | SvgImage;


Lets rename

Suggested change

export type AnyImage = Image | SvgImage;

export type Image = RasterImage | SvgImage;

Renamed in 08a850f

diegomura · 2026-04-11T09:44:24Z

Nit. Maybe just have all this logic inside the svg.ts file and avoid having the svg dir. I'd like to keep the src file structure flat as it's a simple package. Maybe you can create a dom-parser.ts file with the polyfill

diegomura · 2026-04-11T09:53:39Z

    const child = instance.children[i];

-    if (isImage(child)) {
+    if (isImage(child) && isRasterImage(child)) {


Why can't we inline svgs in text? Just not built?

Unfortunately, inline SVG images in <Text> are not currently supported.
The resolveSvgImages step runs before resolveTextLayout (right-to-left composition), converting SVG Image nodes into SvgNodes.
By the time getAttributedString processes Text children, SVG images are no longer Image nodes.
Even if caught earlier, PDFKit's inline attachment API requires a raster image buffer (Buffer), while SVG image data is a string of vector drawing instructions.

diegomura · 2026-04-11T09:57:55Z

+ * allowing them to be processed by the existing SVG rendering pipeline.
+ */
+function resolveSvgImages(node: SafeNode): SafeNode {
+  if (isImage(node) && isSvgImage(node.image)) {


NIt. Maybe just have all checks in isSvgImage. there's no case where isSvgImage should be true but isImage false

diegomura · 2026-04-11T10:00:02Z

Thinking out loud: I wonder if we shuold not include this logic on resolveAssets or resolveSVG step... to me it's kind of in the middle. I don't mind having it as a separate step either if you still prefer it. I just don't wanna end having a pipeline of too many steps (in the future)

Merged into resolveSVG 02ab3e9
The conversion from SVG Image to SvgNode is naturally part of SVG resolution.
It runs right before SVG processing, so keeping them in one step avoids an extra pipeline stage.

resolveAssets is async and focused on fetching images, fonts, etc.
But SVG image conversion is a synchronous tree transformation.
Also, resolveAssets runs twice in the pipeline, so merging into it would run the conversion twice unnecessarily.

diegomura

utACK

Thanks!

@react-pdf/renderer@4.4.1+ depends on @react-pdf/layout@^4.5.1 which allows installation of @react-pdf/layout@4.6.0, which depends on @react-pdf/image@3.1.0, which depends on @react-pdf/svg@^1.1.0. @react-pdf/svg does not exist in npm registry (upstream publish error). Solution: Override @react-pdf/image to 3.0.4 which doesn't depend on svg. Dependency chain before fix: @react-pdf/renderer@4.4.1 → @react-pdf/layout@4.6.0 → @react-pdf/image@3.1.0 → @react-pdf/svg ❌ After fix: @react-pdf/renderer@4.4.1 → @react-pdf/layout@4.6.0 → @react-pdf/image@3.0.4 (override) ✅ Upstream PR: diegomura/react-pdf#3281

exoego force-pushed the svg-image branch 3 times, most recently from ea49f2a to ac445c0 Compare January 24, 2026 07:00

diegomura force-pushed the master branch from c7413a7 to 464b3f1 Compare April 5, 2026 00:54

diegomura reviewed Apr 11, 2026

View reviewed changes

exoego force-pushed the svg-image branch from 03d1d97 to 0c18768 Compare April 11, 2026 12:36

exoego added 4 commits April 11, 2026 21:38

feat: support external SVG via Image tag

b2092ae

reactor: implement own XML parser to avoid huge dependency

de20194

refactor: rename type

08a850f

refactor: simplify resolveSvgImages

6959902

exoego force-pushed the svg-image branch from 0c18768 to 6959902 Compare April 11, 2026 12:38

Merge resolveSvgImages step into resolveSvg

02ab3e9

exoego requested a review from diegomura April 11, 2026 13:09

diegomura approved these changes Apr 11, 2026

View reviewed changes

diegomura merged commit 0138fdd into diegomura:master Apr 11, 2026
8 checks passed

github-actions Bot mentioned this pull request Apr 11, 2026

chore: release packages #3362

Merged

exoego deleted the svg-image branch April 11, 2026 21:16

	export type AnyImage = Image \| SvgImage;
	export type Image = RasterImage \| SvgImage;

Uh oh!

Conversation

exoego commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Flow

Other changes

Attributions to SVG files

Uh oh!

changeset-bot Bot commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

diegomura left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

diegomura Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

exoego Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

diegomura left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

exoego commented Jan 21, 2026 •

edited

Loading

changeset-bot Bot commented Jan 21, 2026 •

edited

Loading

diegomura Apr 11, 2026 •

edited

Loading

exoego Apr 11, 2026 •

edited

Loading