Options

Viewer

import { Viewer } from '@react-pdf-viewer/core';

The Viewer component has the following props:

*: Required prop

PropTypeDescriptionFrom
characterMapobjectSupport non-latin characters via cmap1.7.0
defaultScalenumber or SpecialZoomLevelThe default zoom level1.0.0
fileUrl*string or Uint8ArrayThe path to document1.0.0
httpHeadersobjectThe additional authentication headers to load the document2.2.0
initialPagenumberThe initial page1.4.0
localizationLocalizationMapDefine the localized texts1.0.0
pluginsPlugin[]Array of plugin instances2.0.0
renderErrorFunctionThe error renderer1.6.0
renderLoaderFunctionThe loader renderer2.0.0
renderPageFunctionPage renderer1.5.0
themestringThe theme name2.6.0
transformGetDocumentParamsFunctionTransform more options of pdf.js getDocument API2.5.0
withCredentialsbooleanAllow to load the document from protected resource2.3.0
onDocumentLoadFunctionInvoked when document is loaded1.2.0
onPageChangeFunctionInvoked when when user changes page1.7.0
onZoomFunctionInvoked when zooming document1.2.0

characterMap

Support non-latin characters. It's an object that contains two properties:

ParameterTypeDescription
url*stringIndicate the URL that we can load the character maps
isCompressedbooleanIndicate the character maps are compressed or not

The character maps can be downloaded direclty from Github or loaded from the unpkg.

Here is an example of using the characterMap option:

import { CharacterMap, Viewer } from '@react-pdf-viewer/core';

const characterMap: CharacterMap = {
    isCompressed: true,
    // The url has to end with "/"
    url: 'https://unpkg.com/pdfjs-dist@2.6.347/cmaps/',
};

<Viewer
    characterMap={characterMap}
    fileUrl='/path/to/document.pdf'
/>

defaultScale

The default zoom level.

If it's not set, the initial zoom level will be calculated based on the dimesion of page and the container width. So that, the document will fit best within the container.

Example

fileUrl

The path to document.

import { Viewer } from '@react-pdf-viewer/core';

<Viewer
    fileUrl="/path/to/document.pdf"
/>

From v1.5.0, the fileUrl option can be an Uint8Array. See the Preview a pdf file from an array of bytes example.

From v1.6.0, changing fileUrl will force the viewer to rerender.

Example

httpHeaders

The additional authentication headers that are used to load the document from a protected resource.

<Viewer
    fileUrl={...}
    httpHeaders={{
        key: value,
    }}
    withCredentials={true}
/>

initialPage

The zero-based index of page that will be displayed initially.

<Viewer
    // Display the third page initially
    initialPage={2}
/>

Examples

plugins

An array of plugin instances that bring more functionalities to the viewer.

Following is an example of using the bookmark plugin:

import { bookmarkPlugin } from '@react-pdf-viewer/bookmark';

// Create new plugin instance
const bookmarkPluginInstance = bookmarkPlugin();

// Render
<Viewer
    fileUrl='/assets/pdf-open-parameters.pdf'
    plugins={[
        bookmarkPluginInstance,
    ]}
/>

The plugins page lists built-in plugins.

renderError

Customize the error renderer. It accepts a LoadError parameter and returns an element. The LoadError type consists of the following members:

ParameterTypeDescriptionFrom
messagestringThe error message1.6.0
namestringThe name of exception1.6.0

The name property can take one of the values below:

  • AbortException
  • FormatError
  • InvalidPDFException
  • MissingPDFException
  • PasswordException
  • UnexpectedResponseException
  • UnknownErrorException

Example

renderLoader

Customize the loader renderer. By default, the Viewer component will use the default spinner (Spinner) to indicate that a document is being loaded.

The renderLoader option comes in handy if your document is big, and you want to let your users know how many percentages the document is loaded.

It's a function that takes percentages option and returns a React element.

Here is a snippet code of using the built-in ProgressBar component to show the loading progress:

import { ProgressBar } from '@react-pdf-viewer/core';

// Your render function
<Viewer
    fileUrl="..."
    renderLoader={(percentages: number) => (
        <div style={{ width: '240px' }}>
            <ProgressBar progress={Math.round(percentages)} />
        </div>
    )}
/>

Of course, you can replace ProgressBar with your own progress bar.

Example

renderPage

Customize page renderer. It accepts a RenderPageProps parameter and returns an element.

The RenderPageProps type consists of the following members:

ParameterTypeDescriptionFrom
annotationLayerSlotThe annotation layer1.5.0
canvasLayerSlotThe canvas layer1.5.0
docPdfJs.PdfDocumentThe PDF document1.5.0
heightnumberThe height of page1.5.0
pageIndexnumberThe page index1.5.0
rotationnumberThe current number of rotation degrees1.5.0
scalenumberThe current zoom level1.5.0
svgLayerSlotThe SVG layer1.5.0
textLayerSlotThe text layer1.5.0
widthnumberThe width of page1.5.0

Examples

theme

The theme name. The following built-in themes are available:

Theme    Description
autoSwitch to the dark or light mode automatically based on the system setting
darkThe dark theme
lightThe light theme (default)

transformGetDocumentParams

The option is a function that transforms the parameters of pdf.js getDocument API. You can use it to pass more options to the pdf.js getDocument method.

import { PdfJs } from '@react-pdf-viewer/core';

<Viewer
    fileUrl='...'
    transformGetDocumentParams={(options: PdfJs.GetDocumentParams) => ( 
        Object.assign({}, options, {
            disableRange: false,
            disableStream: false,
        })
    )}
/>

withCredentials

Indicate the cross-site requests should be made with credentials such as cookie and authorization headers. The default value is false.

<Viewer
    fileUrl={...}
    withCredentials={true}
/>

If you want to use another authorization servers or send more additional authentication headers, then use the httpHeaders option.

onDocumentLoad

The callback which is invoked when the document is completely loaded.

import { DocumentLoadEvent, Viewer } from '@react-pdf-viewer/core';

const onDocumentLoad = (e: DocumentLoadEvent) => {
    console.log(`Number of pages: ${e.doc.numPages}`);
};

<Viewer
    fileUrl="/path/to/document.pdf"
    onDocumentLoad={onDocumentLoad}
/>

The DocumentLoadEvent event object contains the following properties:

ParameterTypeDescriptionFrom
docPdfJs.PdfDocumentThe PDF document1.7.0

onPageChange

The callback which is invoked when user changes page.

import { PageChangeEvent, Viewer } from '@react-pdf-viewer/core';

const onPageChange = (e: PageChangeEvent) => {
    // ...
};

<Viewer
    fileUrl='/path/to/document.pdf'
    onPageChange={onPageChange}
/>

The PageChangeEvent event object contains the following properties:

ParameterTypeDescriptionFrom
currentPagenumberThe current page (zero based) index1.7.0
docPdfJs.PdfDocumentThe PDF document1.7.0

Example

onZoom

The callback which is invoked when user zooms the document.

import { Viewer, ZoomEvent } from '@react-pdf-viewer/core';

const onZoom = (e: ZoomEvent) => {
    console.log(`Zoom to ${e.scale}`);
};

<Viewer
    fileUrl="/path/to/document.pdf"
    onZoom={onZoom}
/>

The ZoomEvent event object contains the following properties:

ParameterTypeDescriptionFrom
docPdfJs.PdfDocumentThe PDF document1.7.0
scalenumberThe current scale level1.7.0

Worker

import { Worker } from '@react-pdf-viewer/core';

The Worker component has the following props:

*: Required prop

PropTypeDescriptionFrom
workerUrl*stringThe path to pdfjs' worker1.0.0
import { Worker } from '@react-pdf-viewer/core';

<Worker workerUrl="https://unpkg.com/pdfjs-dist@2.5.207/build/pdf.worker.min.js">
    ...
</Worker>

What is next?

The main viewer component from the @react-pdf-viewer/core package does not provide other parts such as toolbar or sidebar.

It is the time to explore the built-in plugins to bring more functionalities to the viewer.