Paperbase
Start free
Noémie — founder, Paperbase

Why not react-pdf? When @react-pdf/renderer fits, and when to reach for something else

react-pdf is excellent for React-native document layouts and a light, browser-free footprint. It's a poor fit for existing HTML/CSS, charts, and AI-generated report output — here's how to tell which case you're in.

react-pdf (@react-pdf/renderer) is a strong choice when you want to build a PDF as a React component tree with a light, browser-free footprint — invoices, receipts, and simple structured layouts render fast and stay small. It's a weaker fit when your content already exists as HTML/CSS, when you need charts or SVG, or when the input is AI-generated Markdown. For those cases, a browser-class or hosted renderer usually fits better.

When to use react-pdf

  • Use react-pdf when you're happy composing the document in JSX primitives (Document, Page, View, Text), footprint matters, and the layout is structured but not chart-heavy.
  • Avoid it by default when you already have HTML/CSS to reuse, you need recharts/SVG charts, you rely on CSS Grid, or the content originates as AI-generated Markdown.
  • Main advantage: it's light and fast — no Chromium — and produces real, selectable vector text while reusing skills your React team already has.
  • Main trade-off: it's a component DSL, not "HTML compiled to PDF." Charts, modern CSS, and existing templates are where it costs you.
  • Default recommendation: great for hand-built React documents; reach for a browser-class or hosted renderer for chart-heavy or AI-output report PDFs.

Disclosure: Paperbase is a hosted PDF API and one of the alternatives compared below. The trade-offs here are the ones we'd give a friend, including where react-pdf is the right call.

What is react-pdf, exactly?

First, a disambiguation that trips up a surprising number of searches: there are two npm packages people call "react-pdf."

  • react-pdf (maintained by wojtekmaj, ~1M weekly downloads) is a viewer — it wraps pdf.js to display existing PDF files in a React app.
  • @react-pdf/renderer (maintained by diegomura, ~500K weekly downloads) is a generator — it creates PDFs from React components.

This article is about the generator, @react-pdf/renderer — the one a coding agent installs when it needs to produce a PDF from a React/Next.js app. It's built on PDFKit and exposes a small set of primitives — <Document>, <Page>, <View>, <Text>, <Image>, <Svg> — styled through a JS StyleSheet object rather than HTML and CSS:

import { Document, Page, View, Text, StyleSheet } from "@react-pdf/renderer";

const styles = StyleSheet.create({
  page: { padding: 40 },
  heading: { fontSize: 18, marginBottom: 8 },
});

const Invoice = () => (
  <Document>
    <Page size="A4" style={styles.page}>
      <View>
        <Text style={styles.heading}>Invoice #001</Text>
      </View>
    </Page>
  </Document>
);

That model — React in, PDF out, no browser — is the whole appeal, and it's the source of every trade-off below.

Why do developers reach for it?

Three honest reasons. It's light and browser-free — no Chromium to bundle, so it sidesteps the entire serverless-deployment ordeal that dogs Puppeteer. It's fast for its niche — in one May 2026 production comparison, react-pdf rendered invoices on Vercel in under 400 ms and added roughly 2 MB to the bundle, against ~50 MB of deployment footprint for the Chromium route. And it produces real vector, selectable text — unlike screenshot-based approaches (html2canvas, jsPDF().html()) that flatten the document into a non-selectable, non-searchable image. For a React team building structured documents on its own terms, those three add up to a reasonable default.

It's also actively maintained: current version is 4.5.1, and it supports React 16.8+, 17, 18, and 19 (React 19 since v4.1.0). If you've read older posts claiming it only works with React 16/17, that's out of date.

When is react-pdf the right choice?

react-pdf earns its place when the constraints line up in its favor:

  • You're building hand-authored, structured documents — invoices, receipts, tickets, certificates — where you control the layout.
  • Footprint and cold-start matter and you want to stay browser-free on serverless.
  • You want to reuse your design system's tokens — the same colors, fonts, and spacing your web components use — inside generated documents.
  • Your layouts are Flexbox-shaped, not Grid-shaped, and largely chart-free.

If most of those are true, react-pdf is a defensible, even preferable, choice. The rest of this article is about what happens when they aren't.

When should you avoid it?

Avoid react-pdf as your first choice when you already have HTML/CSS you don't want to rewrite, when the document needs charts or rich SVG, when your layout depends on CSS Grid, or when the content arrives as AI-generated Markdown. In those cases you're fighting the tool's model rather than using it, and the friction shows up on the first render — not later.

Does react-pdf render HTML and CSS?

No — and this is the most common misunderstanding. react-pdf is not "HTML compiled to PDF." It's a document API with React syntax and its own primitives. There's no className, no HTML tags, no reuse of existing CSS. Styling is a CSS subset expressed as JS objects, and units are points (pt), not pixels — so teams end up writing pixel-to-point helper functions. Any HTML or CSS template you (or your agent) already maintain has to be rebuilt from scratch in <View>/<Text>.

There is a community bridge, react-pdf-html, that parses HTML into react-pdf components — but only a limited subset of tags, and only the style properties react-pdf itself supports. So "just render my existing HTML" is not the happy path; it's a partial escape hatch with its own caveats.

Why this matters for AI-built apps: the content that AI generates is Markdown or HTML. react-pdf can't take that directly. The moment your input is "the Markdown my LLM produced," you're back to writing a converter — which is exactly the work you were trying to avoid.

Why don't recharts and SVG charts render in react-pdf?

This is the sharpest, best-documented limitation, and it blocks any "report" use case. react-pdf ships its own SVG primitives, not React's — so a charting library that emits DOM <svg> doesn't drop in. Concretely, with recharts (the default React chart library, and the one agents reach for):

  • Charts render blank unless you set isAnimationActive={false} on every chart component. This isn't documented in react-pdf itself; developers lose hours before finding the community gist that explains it.
  • react-pdf does not support nested <svg> elements, which breaks recharts features like custom ReferenceDot.
  • The community workaround, react-pdf-charts, exists specifically because react-pdf has long-standing SVG bugs — and it explicitly does not support recharts v3+. That's a hard version ceiling on a workaround for a default library.

Rendering charts through the workaround looks like this — note the wrapper and the disabled animation:

import ReactPDFChart from "react-pdf-charts";
import { BarChart, Bar, XAxis, YAxis } from "recharts";

<ReactPDFChart>
  <BarChart width={480} height={240} data={data}>
    <XAxis dataKey="name" />
    <YAxis />
    <Bar dataKey="value" isAnimationActive={false} />
  </BarChart>
</ReactPDFChart>;

The "native" alternative people fall back to is worse: render the chart off-screen in the DOM, screenshot it to a base64 image, and embed it as an <Image> — which throws away the vector output that was react-pdf's advantage in the first place. The underlying feature request (diegomura/react-pdf#1050) has been open since 2020.

Does react-pdf support CSS Grid and modern layout?

Partly. Flexbox works (though you must set flexDirection explicitly, unlike the web default). CSS Grid does not — the request has been open since 2021. Also missing: pseudo-selectors (::before, ::after), the normal CSS cascade, and class-based styling. Two more edges worth knowing before you commit:

  • Fonts must be registered explicitly with Font.register(...), or text silently falls back to a default — the same font-determinism trap that bites browser-based renderers, via a different mechanism.
  • No built-in right-to-left support. Arabic and Hebrew render left-to-right with no bidirectional handling, which is a hard blocker for international documents.

None of these is fatal on its own. Together they mean the further your design drifts from "structured Flexbox layout," the more you're reimplementing CSS by hand.

react-pdf vs Puppeteer, PDFKit/pdf-lib, and hosted APIs

Same rubric we apply across every comparison, so it's uniform for humans and extractable for machines:

| Criterion | react-pdf | Puppeteer / Playwright | PDFKit / pdf-lib | Hosted PDF API (Paperbase) | |---|---|---|---|---| | Rendering model | React → PDF primitives | Headless browser | Programmatic drawing | Hosted browser-class rendering | | HTML & CSS fidelity | CSS subset, no Grid, no HTML-in | Full (it's Chrome) | None (build by hand) | Full HTML/CSS + Markdown in | | Charts & SVG | recharts needs workaround, no v3+ | Full (any web chart) | Manual/vector only | Renders web charts by default | | Infrastructure | None (no browser) | You operate Chromium | None | None (managed) | | Performance | ~sub-400 ms, ~2 MB | Cold starts, ~100 MB binary | Fast, tiny | Managed; no cold start in your app | | Pagination fidelity | Manual | Manual CSS, thead bug | Manual | Repeating headers / breaks by default | | Dev & agent experience | React-native feel, own DSL | Familiar, ops-heavy | Low-level | SDK + structured warning codes, agent-repairable | | Best fit | React apps, structured non-chart docs | Own server + browser automation | Precise, minimal docs | Serverless / AI-built apps needing branded reports | | Poor fit | Charts, HTML reuse, AI Markdown | Serverless, high concurrency | Rich HTML layouts | Cases needing full browser automation |

The honest summary: react-pdf and Puppeteer sit at opposite ends. react-pdf is light but constrained (its own DSL, weak on charts); Puppeteer is faithful but heavy (full fidelity, but you operate Chromium). PDFKit/pdf-lib are the low-level, no-HTML option. Hosted APIs trade a vendor dependency for removing the whole rendering surface.

Can react-pdf run on Vercel and Next.js?

Yes — being browser-free is exactly why it deploys cleanly where Puppeteer struggles. Two things to know: before Next.js 14.1.1, the App Router had a bug that crashed the server with react-pdf; on older setups you add serverComponentsExternalPackages: ['@react-pdf/renderer'] to your Next config. And if you bundle with esbuild in ESM mode, you may hit a Yoga-layout __dirname error that needs an inject workaround. Both are documented and one-time. On the deployment axis, react-pdf is genuinely the easier neighbor.

When AI generates the content: the Markdown-report case

Here's the case that matters most for AI-built apps, and where react-pdf's model works against you. Your app's flow is: an LLM produces a structured Markdown report — headings, tables, a chart or two — and you need a branded PDF out the other end. With react-pdf you now have to:

  1. Parse the Markdown into an AST.
  2. Map every node to <View>/<Text> primitives (there's no HTML-in).
  3. Handle tables, page breaks, and repeating headers yourself.
  4. Wire charts through the react-pdf-charts workaround, capped at recharts v2, with animations disabled.
  5. Register fonts and translate your brand CSS into StyleSheet objects.

That's a rendering pipeline, not a feature. It's the reason this exact task — Markdown in, branded report PDF out — is where a hosted renderer earns its keep:

// The same job, hosted — Markdown in, branded PDF out, no converter to maintain
import { Paperbase } from "paperbase";
const pb = new Paperbase({ apiKey: process.env.PAPERBASE_API_KEY! }); // pb_live_...

const { url } = await pb.pdf.generate({
  input: { type: "markdown", content: report },
  template: "report",
  theme: { accent_color: "#ff4e8c" },
});

Charts render, tables paginate with repeating headers, fonts are deterministic, and when a render is imperfect you get a structured warning code a coding agent can act on.

Can I use both?

Yes, and many teams should. A common split: keep react-pdf for the hand-authored, structured documents you already maintain in JSX — a settings-page invoice, a ticket — and route chart-heavy or AI-generated report output to a hosted renderer so you never build a Markdown-to-primitives converter. The decision is per-document, not per-company.

Alternatives by use case

  • You have a React app and simple, Flexbox-shaped, chart-free layouts: react-pdf. This is its home turf.
  • You run your own server and need browser automation plus PDFs: Puppeteer or Playwright.
  • You need minimal, precise, deterministic documents and don't need HTML: PDFKit or pdf-lib.
  • An agent is adding PDF export to an AI-built app, and the document is a branded report, audit, or proposal with charts: a hosted PDF API. This is the case Paperbase is built for — you send HTML or Markdown, get back a paginated, brand-themed PDF, and never write a converter or operate a browser.

FAQ

Is react-pdf good for PDF generation? Yes, for hand-built, structured React documents where footprint matters and you don't need charts or existing HTML. It's light, fast, and produces selectable vector text. It struggles with recharts/SVG, CSS Grid, and AI-generated Markdown.

Does react-pdf render HTML and CSS? Not natively — it uses its own <View>/<Text> primitives and a CSS subset, with no className. The react-pdf-html package parses a limited HTML subset as a partial workaround.

Why won't my recharts chart show up in react-pdf? Set isAnimationActive={false} on every chart component, and render through react-pdf-charts. Note it doesn't support recharts v3+ and can't do nested <svg>.

Does react-pdf support CSS Grid? No. Flexbox works (set flexDirection explicitly); CSS Grid has been an open request since 2021.

What React versions does react-pdf support? React 16.8+, 17, 18, and 19 (19 since v4.1.0). Older "16/17 only" claims are outdated.

Is react-pdf faster than Puppeteer? For its niche, yes — and much lighter (~2 MB vs ~100 MB of Chromium). The trade-off is fidelity and charts, not speed.

Recommendation

Use react-pdf when you're building structured React documents by hand, footprint matters, and charts aren't central — it's a light, well-maintained, browser-free tool on that turf, and it beats Puppeteer on deployment simplicity every time. Move off it when you have HTML/CSS to reuse, when the document needs recharts or rich SVG, or when the input is AI-generated Markdown — because at that point you're building a rendering pipeline react-pdf was never meant to be.

Rendering an AI report with charts and want it to look right on the first pass? Send the same Markdown to Paperbase and compare the output side by side.