React-pdf

Advanced

Page wrapping

Semantically, the <Page /> component represents a single page in the rendered document. However, there are scenarios in which you would expect to have page breaks whenever the page contents exceed their limits, specially when handling big chunks of text. After all, PDFs are paged documents. React-pdf has a build-in wrapping engine that is enabled by default, so you can start creating paged documents right out of the box. If that's not what you need, you can disable this very easily by doing:

import { Document, Page } from '@react-pdf/renderer'

const doc = () => (
  <Document>
    <Page wrap={false}>
      // something pretty here
    </Page>
  </Document>
);

Breakable vs. unbreakable components

We can identify two different types of components based on how they wrap:

• Breakable components try to fill up the remaining space before jumping into a new page. By default, this group is composed by View, Text and Link components
• Unbreakable components are indivisible, therefore if there isn't enough space for them they just get rendered in the following page. In this group by default we only find Image.

Disabling component wrapping

React-pdf also enables you to transform breakable elements into their opposite, forcing them to always render in a new page. This can be done by simply setting the prop wrap={false} to any valid component:

import { Document, Page, View } from '@react-pdf/renderer'

const doc = () => (
  <Document>
    <Page wrap>
      <View wrap={false}>
        // fancy things here
      </View>
    </Page>
  </Document>
);

Now, if the <View /> component happens to be at the bottom of the page without enough space, it will be rendered in a new page as it would be unbreakable.

Page breaks

Page breaks are useful for separating concerns inside the document, or ensuring that a certain element will always show up on the top of the page.

Adding page breaks in react-pdf is very simple: all you have to do is add the break prop to any primitive. This will force the wrapping algorithm to start a new page when rendering that element.

import { Document, Page, Text } from '@react-pdf/renderer'

const doc = () => (
  <Document>
    <Page wrap>
      <Text break>
        // fancy things here
      </Text>
    </Page>
  </Document>
);

Fixed components

There is still another scenario we didn't talk about yet: what if you want to wrap pages but also be able to render a component on all pages? This is where the fixed prop comes into play.

import { Document, Page, View } from '@react-pdf/renderer'

const doc = () => (
  <Document>
    <Page wrap>
      <View fixed>
        // fancy things here
      </View>
    </Page>
  </Document>
);

Just by that, the <View /> component will be placed repeatedly throughout all pages.

Protip: This feature can be very handy for creating nice headers, footers or page numbers, among other use cases. You can even absolutely position fixed elements on your page to create more complex layouts!

On the fly rendering Web only

There are some cases in which you may need to generate a document without showing it on screen. For those scenarios, react-pdf provides two different solutions:

Download link

Is it possible that what you need is just a "Download" button. If that's the case, you can use <PDFDownloadLink /> to easily create and download your document.

import { PDFDownloadLink, Document, Page } from '@react-pdf/renderer'

const MyDoc = () => (
  <Document>
    <Page>
      // My document data
    </Page>
  </Document>
)

const App = () => (
  <div>
    <PDFDownloadLink document={<MyDoc />} fileName="somename.pdf">
      {({ blob, url, loading, error }) => (loading ? 'Loading document...' : 'Download now!')}
    </PDFDownloadLink>
  </div>
)

Protip: You still have access to blob's data if you need it.

Access blob data

However, react-pdf does not stick to just download the document but also enables direct access to the document's blob data for any other possible use case. All you have to do is make use of <BlobProvider />.

import { BlobProvider, Document, Page } from '@react-pdf/renderer';

const MyDoc = (
  <Document>
    <Page>
      // My document data
    </Page>
  </Document>
);

const App = () => (
  <div>
    <BlobProvider document={MyDoc}>
      {({ blob, url, loading, error }) => {
        // Do whatever you need with blob here
        return <div>There's something going on on the fly</div>
      }}
    </BlobProvider>
  </div>
);

You can also obtain the blob data imperatively, which may be useful if you are using react-pdf on a non-React frontend.

import { pdf, Document, Page } from '@react-pdf/renderer';

const MyDoc = (
  <Document>
    <Page>
      // My document data
    </Page>
  </Document>
);

const blob = pdf(MyDoc).toBlob();

Orphan & widow protection

When you layout text, orphans and widows can make the difference between a good document and a great one. That's why react-pdf has a built-in orphan and widow protection that you can use right out of the box.

But react-pdf does not reserve this protection just for text. You can adjust this protection to your convenience by just setting some props to any react-pdf primitive:

Protip: You can use this API to ensure that headings do not get rendered at the bottom of a page

Dynamic content

With react-pdf, now it is possible to render dynamic text based on the context in which a certain element is being rendered. All you have to do is to pass a function to the render prop of the <Text /> or <View /> component. The result will be rendered inside the text block as a child.

import { Document, Page } from '@react-pdf/renderer'

const doc = () => (
  <Document>
    <Page wrap>
      <Text render={({ pageNumber, totalPages }) => (
        `${pageNumber} / ${totalPages}`
      )} fixed />

      <View render={({ pageNumber }) => (
        pageNumber % 2 === 0 && (
          <View style={{ background: 'red' }}>
            <Text>I'm only visible in odd pages!</Text>
          </View>
        )
      )} />
    </Page>
  </Document>
);

Available arguments

Bare in mind that the render function is called twice for <Text /> elements: once for layout on the page wrapping process, and another one after it's know how many pages the document will have.

Protip: Use this API in conjunction with fixed elements to render page number indicators

Debugging

React-pdf ships a built-in debugging system you can use whenever you have doubts about how elements are being laid out on the page. All you have to do is to set the debug prop to true on any valid primitive (except Document) and re-render the document to see the result on the screen.

Ruler

If you need fine-grained control on proportions and where elements are rendered, you can use the Ruler props on <Page /> to ease your work. This API enables you to define a fully customizable vertical and/or horizontal grid to visualize how elements arrange inside the page. For grid separation, you can specify both fixed or proportional values.

If you need fine-grained control on proportions and where elements are rendered, you can use the Ruler props on Page to ease your work. This API enables you to define a fully customizable vertical and/or horizontal grid to visualize how elements arrange inside the page. For grid separation, you can specify both fixed or proportional values.

RulerVertical RulerHorizontal Ruler

Hyphenation

Hyphenation refers to the automated process of breaking words between lines to create a better visual consistency across a text block. This is a complex problem. It involves knowing about the language of the text, available space, ligatures, among other things.

React-pdf internally implements the Knuth and Plass line breaking algorithm that produces the minimum amount of lines without compromising text legibility. By default it's setup to hyphenate english words.

If you need more fine-grained control over how words break, you can pass your own callback and handle all that logic by yourself:

import { Font } from '@react-pdf/renderer'

const hyphenationCallback = (word) => {
  // Return word syllables in an array
}

Font.registerHyphenationCallback(hyphenationCallback);

You can use the default hyphenation callback as a starting point.

Protip: If you don't want to hyphenate words at all, just provide a callback that returns the same words it receives. More information here

Webpack config web only

React-pdf is built on top of PDFKit, which for browser usage requires a couple of node.js API shims.

If you use webpack you may need to include the following settings to your config:

{
  ...
  node : {
    module: 'empty',
    dgram: 'empty',
    dns: 'mock',
    fs: 'empty',
    http2: 'empty',
    net: 'empty',
    tls: 'empty',
    child_process: 'empty',
  }
}

If you are using create-react-app, those are already included.