react-pdf vs an embedded report designer

Two shapes, not two libraries

Almost every comparison of these two starts with a feature table, and a feature table is the wrong instrument. Strip both back and the difference is one sentence:

Everything else follows from that. Testing, review, who can make a change, what a customer can be promised, what happens when the fifth tenant wants a different arrangement — all of it is downstream of where the layout is stored.

Which means the question is not “which is better”. It is “does anybody outside engineering need to change these documents”. If the answer is genuinely no, react-pdf is smaller, free, and the better engineering decision, and you can stop reading here with our blessing.

What react-pdf actually is

A React renderer that targets PDF instead of the DOM. You compose Document, Page, View, Text, Image and Link; it lays them out with its own flexbox implementation and draws the result. It does not render HTML or CSS — the styles are a React Native-ish subset, not a browser — which is the single most common surprise for people arriving from print stylesheets.

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

const styles = StyleSheet.create({
  page: { padding: 40, fontSize: 11 },
  row: { flexDirection: "row", borderBottom: "1 solid #ddd", paddingVertical: 4 },
  cell: { flex: 1 }
});

export const Statement = ({ client, lines }: Props) => (
  <Document>
    <Page size="A4" style={styles.page}>
      <Text>Statement for {client.name}</Text>
      {lines.map((line) => (
        <View key={line.id} style={styles.row}>
          <Text style={styles.cell}>{line.description}</Text>
          <Text style={styles.cell}>{line.amount}</Text>
        </View>
      ))}
    </Page>
  </Document>
);

What you get, and it is a lot:

• A real layout engine, so text wraps and boxes grow. No cursor, no manual page-break arithmetic.
• Automatic page wrapping, with page-break control on individual elements.
• Font embedding, browser and Node rendering, and an MIT licence.
• Components. Your document is composable, reviewable and typed, which is a genuinely nice way to work.

What it is not:

• Not HTML. Anything you know about CSS print layout transfers partially at best, and third-party chart libraries that emit SVG or DOM do not drop in.
• Not a table library. There is no table primitive; tables are composed from Views, and a header that repeats after a page break is code you write.
• Not an editor, and not trying to be. That is a legitimate scope decision, not a gap.

What an embedded report designer actually is

The inversion. Instead of writing the document, you write down what could be in one — a typed schema of fields — and hand a visual editor to whoever should be arranging them. What comes back is a serialisable document model, not code.

// The BroadPaper equivalent is not a component. It is a declaration of
// what exists, and then a component that lets somebody else arrange it.
import type { DataSource } from "@broadpaper/core";

export const dataSources: DataSource[] = [
  {
    id: "client",
    label: "Client",
    schema: { name: { type: "string", label: "Client name" } }
  },
  {
    id: "statement",
    label: "Statement",
    schema: {
      lines: {
        type: "array",
        label: "Lines",
        itemSchema: {
          type: "object",
          fields: {
            description: { type: "string", label: "Description" },
            amount: { type: "currency", label: "Amount", currency: "GBP" }
          }
        }
      }
    }
  }
];

// …and then <ReportDesigner dataSources={dataSources} onSave={save} />.
// Nothing above says where anything goes on the page. That is the point.

Notice what is absent from that file. There is no page, no ordering, no styling and no mention of where anything goes. That is the entire contract: you say what exists, somebody else says where it goes, and the SDK is responsible for everything in between — measurement, page breaks, repeated table headers, branding, fonts and the finished file.

The output of the editor is JSON, which is the property that makes the rest tractable. A layout you can store is a layout you can version, diff, copy between tenants, validate on the way in and roll back. A layout that is code is none of those things without a deployment.

The cost of the seam

Teams almost always underestimate the middle ground — “we'll just make our react-pdf components configurable”. It is worth pricing properly, because it is the option that looks cheapest and is not.

Making a code-defined document user-editable means building, in order:

1. A serialisable format. Some JSON your components can be driven by. This is a document model, and designing one is a week you will spend twice.
2. An interpreter. The thing that turns that JSON back into components, including conditionals and lists.
3. An editor. Drag, drop, select, undo, redo, keyboard, a properties panel, and a preview that agrees with the output.
4. A binding layer. Some way for a non-developer to say “this text is the client's name”, with a picker and some type checking, without letting them write JavaScript.
5. Validation. Because now users can save documents that cannot render, and you have to catch that before a customer does.
6. Versioning. Because saved layouts outlive the schema they were written against.

There is a fourth option people forget: keep the documents in code and get faster at changing them. A tight deployment pipeline and a component library for documents genuinely solves this for a lot of teams, and it is the right answer when the changes are frequent but always come through you.

How to decide

Facts about react-pdf here come from react-pdf.org and its repository, checked on the date at the top of this page. If something has changed, tell us at hello@broadpaper.com and we will correct it.

Using both

This is not a migration story and there is no converter — a react-pdf document is code and a BroadPaper report is data, so nothing translates between them. The teams who end up with both do it deliberately:

• In code: documents whose layout is prescribed by somebody else. A statutory notice, a regulator's form, an insurance schedule with a legally required order. You want those in version control where a reviewer can see them change.
• In the designer: everything customer-facing and negotiable. Client reports, statements, proposals, packs, certificates — the documents where “can we move this” is a reasonable thing for a customer to ask.

If you want the two compared row by row rather than argued about, here is the table. If you are specifically trying to work out the architecture for user-designed reports in a React app, that has its own guide.