react-pdf-image-resolver

Fix react-pdf Image not loading (CORS, SVG, remote URLs). Resolve S3/CDN logos, SVG, and data URLs to PNG data URLs so @react-pdf/renderer's <Image> can display them in PDFs—invoices, reports, quotes.

• react-pdf image CORS – Fetch images in your app and pass a data URL so react-pdf never hits cross-origin.
• react-pdf SVG – Convert SVG to PNG (react-pdf does not support SVG).
• react-pdf logo from S3 – Encode URLs with spaces and normalize application/octet-stream to image/png.

Table of contents

• Why use this?
• Requirements
• Install
• Quick start
• API
• Usage examples
• Remote URLs and CORS
• Troubleshooting
• License

Why use this?

When you pass a remote image URL (e.g. from S3) directly to react-pdf's <Image src={url} />, it often fails:

• CORS – react-pdf fetches images with XHR. Browsers block cross-origin responses unless the server sends the right headers. This package fetches the image in your app and passes a data URL, so react-pdf never does a cross-origin request.
• SVG – react-pdf's Image does not support SVG. This package converts SVG to PNG so it can be embedded.
• URLs with spaces / wrong Content-Type – Paths like .../My Logo or files without extensions can break or be served as application/octet-stream. The package encodes URLs and normalizes the result to a proper image/png data URL.

Requirements

• Browser environment (uses fetch, Image, canvas, FileReader). Not for Node.js.
• Works with any app using @react-pdf/renderer.

Install

npm install react-pdf-image-resolver

Quick start

Resolve your image URL before rendering the PDF, then pass the result to <Image>:

import { Document, Image, Page, pdf } from "@react-pdf/renderer";
import { resolveImageForPdf } from "react-pdf-image-resolver";

// Before generating the PDF, resolve the logo (e.g. from your API, state, or config)
const logoDataUrl = await resolveImageForPdf({
  url: "https://example.com/logo.png",
  fallbackUrl: "/default-logo.png",
});

// Use the returned data URL in your PDF component
const MyDocument = () => (
  <Document>
    <Page>
      <Image src={logoDataUrl} />
    </Page>
  </Document>
);

const blob = await pdf(<MyDocument />).toBlob();

API

resolveImageForPdf(options)

Parameters

| Option | Type | Default | Description | | ------------- | --------------- | ------- | ----------- | | url | string | - | Image URL to resolve: remote (http/https), data URL, or relative. Can be null or omitted if you provide fallbackUrl. | | maxWidth | number | "auto" | 200 | Maximum width when resizing. Use "auto" to scale by height only (width follows aspect ratio). | | maxHeight | number | "auto" | 80 | Maximum height when resizing. Use "auto" to scale by width only (height follows aspect ratio). | | resolutionScale | number | 1 | Generate at this multiple of maxWidth/maxHeight (e.g. 2 or 3) for sharper logos when displaying small. Use the same maxWidth/maxHeight as your PDF display size. | | fallbackUrl | string | - | If url fails to load or convert, this value is returned. Use a local or default image URL so the PDF always has a logo. |

You must pass at least one of url or fallbackUrl.

Returns

• Promise<string> – A data:image/png;base64,... URL, or fallbackUrl if resolution fails and fallbackUrl was provided.

Throws

• If both url and fallbackUrl are missing or invalid.
• If resolution fails and no fallbackUrl was provided.

Supported input URLs

| Input | Example | What the package does | | ------------------ | -------------------------------- | ---------------------------------------- | | Remote (HTTP/HTTPS)| https://bucket.s3.amazonaws.com/logo.png | Fetches, then converts to PNG data URL. | | Data URL (image) | data:image/png;base64,... | Normalizes to PNG data URL. | | Data URL (SVG) | data:image/svg+xml;base64,... | Converts to PNG data URL. | | SVG URL | https://example.com/logo.svg | Fetches, then converts to PNG data URL. | | Relative | /assets/logo.png | Returned as-is (no fetch). |

Usage examples

ESM

import { resolveImageForPdf } from "react-pdf-image-resolver";

const dataUrl = await resolveImageForPdf({
  url: companyLogoUrl,
  maxWidth: 120,
  maxHeight: "auto", // height follows aspect ratio; or use a number (e.g. 80)
  fallbackUrl: "/assets/logo.png",
});

CommonJS

const { resolveImageForPdf } = require("react-pdf-image-resolver");

const dataUrl = await resolveImageForPdf({
  url: companyLogoUrl,
  fallbackUrl: "/assets/logo.png",
});

With a “store” or config object

const logoUrl = await resolveImageForPdf({
  url: store?.logo ?? config.logoUrl,
  fallbackUrl: `${window.location.origin}/assets/logo.png`,
});

TypeScript

Type definitions are included. Import the function and options as usual; types are inferred.

import { resolveImageForPdf, type ResolveImageForPdfOptions } from "react-pdf-image-resolver";

const opts: ResolveImageForPdfOptions = {
  url: process.env.LOGO_URL,
  fallbackUrl: "/logo.png",
};
const dataUrl = await resolveImageForPdf(opts);

Remote URLs and CORS

For remote URLs (e.g. S3, CDN), the server must allow requests from your app’s origin. If you see a CORS error in the console, configure your bucket or CDN.

Example S3 CORS configuration (AWS S3 → Bucket → Permissions → CORS):

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedOrigins": ["https://your-app.com", "http://localhost:3000"],
    "ExposeHeaders": []
  }
]

Replace the origins with your real app URL and (for development) http://localhost:PORT.

Troubleshooting

| Issue | What to do | | ------------------------ | ---------- | | CORS error in console | Add CORS headers on the server that hosts the image (e.g. S3 CORS config above). | | Logo missing in PDF | Pass a fallbackUrl so something is always shown when the main url fails. | | SVG not showing | This package converts SVG to PNG; ensure you pass the SVG URL or data URL into resolveImageForPdf and use the returned value in <Image src={...} />. | | “url or fallbackUrl is required” | Provide at least one of url or fallbackUrl in the options object. |

License

MIT