React-pdf

Page wrapping

By default each <Page /> component represents a single page in the rendered document no matter how big their children are. However, there are scenarios in which you would expect to have page breaks whenever the page contents exceeds their limits, specially when handling big chunks of text. React-pdf has a build-in wrapping engine that enables you to do just that very easily:

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

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

And voilà. Now every time an element gets outside the page, it's wrapped to fill the remaining space (if any) and the remaining part is added into a new page. Pretty handy right?

Breakable vs. unbreakable components

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

• Breakable components tries 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 /> components happens to be at the bottom of the page without enough space, it will be rendered in a new page as he 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 I 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>
);

Orphan & widow protection

"An orphan has no past; a widow has no future"

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

Emoji rendering

PDF documents do not support color emoji fonts. This is a bummer for the ones out there who love their expressiveness and simplicity. The only way of rendering this glyphs on a PDF document, is by embedding them as images.

React-pdf makes this task simple by enabling you to use a CDN from where to download emoji images. All you have to do is setup a valid URL (we recommend using Twemoji for this task), and react-pdf will take care of the rest:

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

Font.registerEmojiSource({
  format: 'png',
  url: 'https://twemoji.maxcdn.com/2/72x72/',
});

Protip: react-pdf will need a internet connection to download emoji's images at render time, so bare that in mind when choosing to use this API

Dynamic content

With react-pdf it is now 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 children.

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 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 for yourself:

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

const hyphenationCallback = (words) => {
  // Iterate through words
}

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