Options
Viewer component
import { Viewer } from '@react-pdf-viewer/core';
The `Viewer`
component has the following props:
(* denotes a required property)
Prop | Type | Description | From |
---|
`characterMap` | `object` | Support non-latin characters via `cmap` | 1.7.0 |
`defaultScale` | `number` or `SpecialZoomLevel` | The default zoom level | 1.0.0 |
`fileUrl` * | `string` or `Uint8Array` | The path to document | 1.0.0 |
`httpHeaders` | `object` | The additional authentication headers to load the document | 2.2.0 |
`initialPage` | `number` | The initial page | 1.4.0 |
`initialRotation` | `number` | The initial rotation | 3.8.0 |
`localization` | `LocalizationMap` | Define the localized texts | 1.0.0 |
`pageLayout` | `object` | Modify the styles and size of each page | 3.9.0 |
`plugins` | `Plugin[]` | Array of plugin instances | 2.0.0 |
`renderError` | `Function` | The error renderer | 1.6.0 |
`renderLoader` | `Function` | The loader renderer | 2.0.0 |
`renderPage` | `Function` | Page renderer | 1.5.0 |
`renderProtectedView` | `Function` | Customize the view of a protected document | 3.11.0 |
`scrollMode` | `ScrollMode` | The initial scroll mode | 3.1.0 |
`theme` | `string` or `object` | The theme options | 2.6.0 |
`transformGetDocumentParams` | `Function` | Transform more options of pdf.js `getDocument` API | 2.5.0 |
`viewMode` | `ViewMode` | The initial viewmode | 3.10.0 |
`withCredentials` | `boolean` | Allow to load the document from protected resource | 2.3.0 |
`onDocumentAskPassword` | `Function` | Invoked when a protected document requires a password to open | 2.9.0 |
`onDocumentLoad` | `Function` | Invoked when document is loaded | 1.2.0 |
`onPageChange` | `Function` | Invoked when users change page | 1.7.0 |
`onRotate` | `Function` | Invoked when users rotate the document | 3.2.0 |
`onRotatePage` | `Function` | Invoked when users rotate a single page | 3.2.0 |
`onSwitchTheme` | `Function` | Invoked when users switch theme | 2.7.0 |
`onZoom` | `Function` | Invoked when zooming document | 1.2.0 |
characterMap
Support non-latin characters. It's an object that contains two properties:
Parameter | Type | Description |
---|
`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,
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.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
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:
Property | Type | Description | From |
---|
`buildPageStyles` | `Function` | Add addition styles to each page | 3.9.0 |
`tranformSize` | `Function` | Transform the size of each page | 3.9.0 |
buildPageStyles
buildPageStyles?: ({ numPages: number; pageIndex: number }) => React.CSSProperties;
Property | Type | Description | From |
---|
`numPages` | `number` | The total number of pages | 3.9.0 |
`pageIndex` | `number` | The current page | 3.9.0 |
tranformSize
tranformSize?: ({ numPages: number; pageIndex: number; size: Rect }) => Rect;
Property | Type | Description | From |
---|
`numPages` | `number` | The total number of pages | 3.9.0 |
`pageIndex` | `number` | The current page | 3.9.0 |
`size` | `Rect` | The dimension of current page | 3.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';
const bookmarkPluginInstance = bookmarkPlugin();
<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:
Parameter | Type | Description | From |
---|
`message` | `string` | The error message | 1.6.0 |
`name` | `string` | The name of exception | 1.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';
<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:
Parameter | Type | Description | From |
---|
`annotationLayer` | `Slot` | The annotation layer | 1.5.0 |
`canvasLayer` | `Slot` | The canvas layer | 1.5.0 |
`canvasLayerRendered` | `Boolean` | Indicate that the canvas layer is rendered completely or not | 3.1.0 |
`doc` | `PdfJs.PdfDocument` | The PDF document | 1.5.0 |
`height` | `number` | The height of page | 1.5.0 |
`pageIndex` | `number` | The page index | 1.5.0 |
`rotation` | `number` | The current number of rotation degrees | 1.5.0 |
`scale` | `number` | The current zoom level | 1.5.0 |
`svgLayer` | `Slot` | The SVG layer | 1.5.0 |
`textLayer` | `Slot` | The text layer | 1.5.0 |
`textLayerRendered` | `Boolean` | Indicate that the text layer is rendered completely or not | 3.1.0 |
`width` | `number` | The width of page | 1.5.0 |
`markRendered` | `Function` | Mark as the page rendered completely | 3.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:
Parameter | Type | Description | From |
---|
`passwordStatus` | `PasswordStatus` | The password status enum | 3.11.0 |
`verifyPassword` | `Function` | The function to verify the password | 3.11.0 |
Example
scrollMode
The initial scroll mode. It can be one of the following modes:
Mode | Type | Description |
---|
`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 |
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' />
<Viewer
theme={{
theme: 'dark',
}}
/>
The following built-in themes are available:
Theme | Description | From |
---|
`auto` | Switch to the dark or light mode automatically based on the system setting | 2.6.0 |
`dark` | The dark theme | 2.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,
}}
/>;
<Viewer
theme={{
theme: 'dark',
direction: TextDirection.RightToLeft,
}}
/>;
There are two possible values for the `direction`
option:
Value | Description | From |
---|
`TextDirection.LeftToRight` | Left to right (LTR) direction. It's the default value | 2.8.0 |
`TextDirection.RightToLeft` | Right to left (RTL) direction | 2.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:
Mode | Type | Description |
---|
`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:
Parameter | Type | Description | From |
---|
`doc` | `PdfJs.PdfDocument` | The PDF document | 1.7.0 |
`file` | `OpenFile` | The current opened file | 2.7.2 |
The `OpenFile`
type contains the information of the current opened file:
Property | Type | Description |
---|
`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:
Parameter | Type | Description | From |
---|
`currentPage` | `number` | The current page (zero based) index | 1.7.0 |
`doc` | `PdfJs.PdfDocument` | The PDF document | 1.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:
Parameter | Type | Description | From |
---|
`direction` | `RotateDirection` | The rotate direction | 3.2.0 |
`doc` | `PdfJs.PdfDocument` | The PDF document | 3.2.0 |
`rotation` | `number` | The latest rotation value | 3.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:
Parameter | Type | Description | From |
---|
`direction` | `RotateDirection` | The rotate direction | 3.2.0 |
`doc` | `PdfJs.PdfDocument` | The PDF document | 3.2.0 |
`pageIndex` | `number` | The zero-based page index | 3.2.0 |
`rotation` | `number` | The latest rotation value | 3.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:
Parameter | Type | Description | From |
---|
`doc` | `PdfJs.PdfDocument` | The PDF document | 1.7.0 |
`scale` | `number` | The current scale level | 1.7.0 |
Worker component
import { Worker } from '@react-pdf-viewer/core';
The `Worker`
component has the following props:
(* denotes a required property)
Prop | Type | Description | From |
---|
`workerUrl` * | `string` | The path to pdfjs' worker | 1.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.