Options

Viewer component

import { Viewer } from '@react-pdf-viewer/core';
The `Viewer` component has the following props:
(* denotes a required property)
PropTypeDescriptionFrom
`characterMap``object`Support non-latin characters via `cmap`1.7.0
`defaultScale``number` or `SpecialZoomLevel`The default zoom level1.0.0
`fileUrl`*`string` or `Uint8Array`The path to document1.0.0
`httpHeaders``object`The additional authentication headers to load the document2.2.0
`initialPage``number`The initial page1.4.0
`initialRotation``number`The initial rotation3.8.0
`localization``LocalizationMap`Define the localized texts1.0.0
`pageLayout``object`Modify the styles and size of each page3.9.0
`plugins``Plugin[]`Array of plugin instances2.0.0
`renderError``Function`The error renderer1.6.0
`renderLoader``Function`The loader renderer2.0.0
`renderPage``Function`Page renderer1.5.0
`renderProtectedView``Function`Customize the view of a protected document3.11.0
`scrollMode``ScrollMode`The initial scroll mode3.1.0
`theme``string` or `object`The theme options2.6.0
`transformGetDocumentParams``Function`Transform more options of pdf.js `getDocument` API2.5.0
`viewMode``ViewMode`The initial viewmode3.10.0
`withCredentials``boolean`Allow to load the document from protected resource2.3.0
`onDocumentAskPassword``Function`Invoked when a protected document requires a password to open2.9.0
`onDocumentLoad``Function`Invoked when document is loaded1.2.0
`onPageChange``Function`Invoked when users change page1.7.0
`onRotate``Function`Invoked when users rotate the document3.2.0
`onRotatePage``Function`Invoked when users rotate a single page3.2.0
`onSwitchTheme``Function`Invoked when users switch theme2.7.0
`onZoom``Function`Invoked when zooming document1.2.0

characterMap

Support non-latin characters. It's an object that contains two properties:
ParameterTypeDescription
`url`*`string`Indicate the URL that we can load the character maps
`isCompressed``boolean`Indicate 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.
Examples

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

initialRotation

Set the initial rotation:
<Viewer initialRotation={90} />

pageLayout

Modify the styles and size of each page. It is an object containing the following properties:
PropertyTypeDescriptionFrom
`buildPageStyles``Function`Add addition styles to each page3.9.0
`tranformSize``Function`Transform the size of each page3.9.0
buildPageStyles
buildPageStyles?: ({ numPages: number; pageIndex: number }) => React.CSSProperties;
PropertyTypeDescriptionFrom
`numPages``number`The total number of pages3.9.0
`pageIndex``number`The current page3.9.0
tranformSize
tranformSize?: ({ numPages: number; pageIndex: number; size: Rect }) => Rect;
PropertyTypeDescriptionFrom
`numPages``number`The total number of pages3.9.0
`pageIndex``number`The current page3.9.0
`size``Rect`The dimension of current page3.9.0
The `Rect` type indicates the page dimension including the `height` and `width` properties that represent the height and width of each page, respectively.
Example

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
`message``string`The error message1.6.0
`name``string`The 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
`annotationLayer``Slot`The annotation layer1.5.0
`canvasLayer``Slot`The canvas layer1.5.0
`canvasLayerRendered``Boolean`Indicate that the canvas layer is rendered completely or not3.1.0
`doc``PdfJs.PdfDocument`The PDF document1.5.0
`height``number`The height of page1.5.0
`pageIndex``number`The page index1.5.0
`rotation``number`The current number of rotation degrees1.5.0
`scale``number`The current zoom level1.5.0
`svgLayer``Slot`The SVG layer1.5.0
`textLayer``Slot`The text layer1.5.0
`textLayerRendered``Boolean`Indicate that the text layer is rendered completely or not3.1.0
`width``number`The width of page1.5.0
`markRendered``Function`Mark as the page rendered completely3.1.0
Because the document renders pages one by one, you have to use the `markRendered` method to mark the corresponding page to be rendered completely. Then the next page will be rendered.
It's a function that takes a single `pageIndex` parameter as following:
markRendered: (pageIndex: number) => void;
Examples

renderProtectedView

Customize the view of a protected document:
import { RenderProtectedViewProps, Viewer } from '@react-pdf-viewer/core';
const ProtectedView: React.FC<RenderProtectedViewProps> = ({ passwordStatus, verifyPassword }) => {
...
};
<Viewer renderProtectedView={renderProps => <ProtectedView {...renderProps} />} />
The `RenderProtectedViewProps` type consists of the following members:
ParameterTypeDescriptionFrom
`passwordStatus``PasswordStatus`The password status enum3.11.0
`verifyPassword``Function`The function to verify the password3.11.0
Example

scrollMode

The initial scroll mode. It can be one of the following modes:
ModeTypeDescription
`ScrollMode.Vertical``ScrollMode`The default scroll mode. Scroll the pages in the vertical direction
`ScrollMode.Horizontal``ScrollMode`Scroll the pages in the horizontal direction
`ScrollMode.Page``ScrollMode`Display a single page each time
`ScrollMode.Wrapped``ScrollMode`Scroll the pages in both vertical and horizontal directions
The default value is `ScrollMode.Vertical`. The scroll mode can be changed programmatically by using the scroll mode plugin.

theme

The theme options which indicates the theme name and the text direction.
The theme name: It can be passed as a string or value of the `theme` property as following:
<Viewer theme='dark' />
// Or
<Viewer
theme={{
theme: 'dark',
}}
/>
The following built-in themes are available:
ThemeDescriptionFrom
`auto`Switch to the dark or light mode automatically based on the system setting2.6.0
`dark`The dark theme2.6.0
`light`The light theme (default)2.6.0
The text direction
import { TextDirection } from '@react-pdf-viewer/core';
<Viewer
theme={{
direction: TextDirection.RightToLeft,
}}
/>;
// Use a right-to-left language with the dark theme
<Viewer
theme={{
theme: 'dark',
direction: TextDirection.RightToLeft,
}}
/>;
There are two possible values for the `direction` option:
ValueDescriptionFrom
`TextDirection.LeftToRight`Left to right (LTR) direction. It's the default value2.8.0
`TextDirection.RightToLeft`Right to left (RTL) direction2.8.0
Examples

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,
})
}
/>;

viewMode

The initial viewmode. It can be one of the following modes:
ModeTypeDescription
`ViewMode.SinglePage``ViewMode`The default viewmode. View single page continuously
`ViewMode.DualPage``ViewMode`View two pages each time
`ViewMode.DualPageWithCover``ViewMode`View two pages each time. The first page is displayed as a cover

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.

onDocumentAskPassword

The callback is invoked when a protected document requires a password to open.
import { DocumentAskPasswordEvent, Viewer } from '@react-pdf-viewer/core';
const handleAskPassword = (e: DocumentAskPasswordEvent) => {
// ...
};
<Viewer onDocumentAskPassword={handleAskPassword} />;
Example

onDocumentLoad

The callback which is invoked when the document is completely loaded.
import { DocumentLoadEvent, Viewer } from '@react-pdf-viewer/core';
const handleDocumentLoad = (e: DocumentLoadEvent) => {
console.log(`Number of pages: ${e.doc.numPages}`);
};
<Viewer fileUrl="/path/to/document.pdf" onDocumentLoad={handleDocumentLoad} />;
The `DocumentLoadEvent` event object contains the following properties:
ParameterTypeDescriptionFrom
`doc``PdfJs.PdfDocument`The PDF document1.7.0
`file``OpenFile`The current opened file2.7.2
The `OpenFile` type contains the information of the current opened file:
PropertyTypeDescription
`data``string` or `Uint8Array`It is the file name or `Uint8Array` depending on the type of `fileUrl`
`name``string`The file name
Example

onPageChange

The callback which is invoked when user changes page.
import { PageChangeEvent, Viewer } from '@react-pdf-viewer/core';
const handlePageChange = (e: PageChangeEvent) => {
// ...
};
<Viewer fileUrl="/path/to/document.pdf" onPageChange={handlePageChange} />;
The `PageChangeEvent` event object contains the following properties:
ParameterTypeDescriptionFrom
`currentPage``number`The current page (zero based) index1.7.0
`doc``PdfJs.PdfDocument`The PDF document1.7.0
Example

onRotate

The callback which is invoked when users rotate the document.
import { RotateEvent, Viewer } from '@react-pdf-viewer/core';
const handleRotate = (e: RotateEvent) => {
// ...
};
<Viewer fileUrl="/path/to/document.pdf" onRotate={handleRotate} />;
The `RotateEvent` event object contains the following properties:
ParameterTypeDescriptionFrom
`direction``RotateDirection`The rotate direction3.2.0
`doc``PdfJs.PdfDocument`The PDF document3.2.0
`rotation``number`The latest rotation value3.2.0
`RotateDirection` is an enum with two possible values:
  • `Backward` if users rotate counterclockwise
  • `Forward` if users rotate clockwise

onRotatePage

The callback which is invoked when users rotate a single page of the document.
import { RotatePageEvent, Viewer } from '@react-pdf-viewer/core';
const handleRotatePage = (e: RotatePageEvent) => {
// ...
};
<Viewer fileUrl="/path/to/document.pdf" onRotatePage={handleRotatePage} />;
The `RotatePageEvent` event object contains the following properties:
ParameterTypeDescriptionFrom
`direction``RotateDirection`The rotate direction3.2.0
`doc``PdfJs.PdfDocument`The PDF document3.2.0
`pageIndex``number`The zero-based page index3.2.0
`rotation``number`The latest rotation value3.2.0

onSwitchTheme

The callback which is invoked when users switch themes. It's a function that takes the current theme.
The following snippet demonstrates an example that the current theme is stored in the local storage, and is loaded back in the next user's visit:
const handleSwitchTheme = (theme: string) => {
localStorage.setItem('theme', theme);
};
const theme = localStorage.getItem('theme') || 'light';
<Viewer theme={theme} onSwitchTheme={handleSwitchTheme} />;
Example

onZoom

The callback which is invoked when user zooms the document.
import { Viewer, ZoomEvent } from '@react-pdf-viewer/core';
const handleZoom = (e: ZoomEvent) => {
console.log(`Zoom to ${e.scale}`);
};
<Viewer fileUrl="/path/to/document.pdf" onZoom={handleZoom} />;
The `ZoomEvent` event object contains the following properties:
ParameterTypeDescriptionFrom
`doc``PdfJs.PdfDocument`The PDF document1.7.0
`scale``number`The current scale level1.7.0

Worker component

import { Worker } from '@react-pdf-viewer/core';
The `Worker` component has the following props:
(* denotes a required property)
PropTypeDescriptionFrom
`workerUrl`*`string`The 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.