@pdftron/react-native-pdf/API.md

React Native Pdftron

# PDFTron React Native API

## TypeScript

PDFTron React Native supports TypeScript. Since not all customers use the language, the typings used in this document will be described using normal JavaScript types. For TypeScript users, type information is automatically provided while coding, and exact type aliases and constants used in our custom typings can be found in [AnnotOptions](src/AnnotOptions) and [Config](src/Config) source folders.

## RNPdftron

RNPdftron contains static methods for global library initialization, configuration, and utility methods.

### initialize
Initializes PDFTron SDK with your PDFTron commercial license key. You can run PDFTron in demo mode by passing an empty string.

Parameters:

Name | Type | Description
--- | --- | ---
licenseKey | string | your PDFTron license key

```js
RNPdftron.initialize('your_license_key');
```

### enableJavaScript
Enables JavaScript for PDFTron SDK, by default it is enabled.

Parameters:

Name | Type | Description
--- | --- | ---
enabled | bool | whether to enable or disable JavaScript

```js
RNPdftron.enableJavaScript(true);
```

### getVersion
Gets the current PDFNet version.

Returns a Promise.

Promise Parameters:

Name | Type | Description
--- | --- | ---
version | string | current PDFNet version

```js
RNPdftron.getVersion().then((version) => {
  console.log("Current PDFNet version:", version);
});
```

### getPlatformVersion
Gets the version of current platform (Android/iOS).

Returns a Promise.

Promise Parameters:

Name | Type | Description
--- | --- | ---
platformVersion | string | current platform version (Android/iOS)

```js
RNPdftron.getPlatformVersion().then((platformVersion) => {
  console.log("App currently running on:", platformVersion);
});
```

### getSystemFontList
Gets the font list available on the OS (Android only).
This is typically useful when you are mostly working with non-ascii characters in the viewer.

Returns a Promise.

Promise Parameters:

Name | Type | Description
--- | --- | ---
fontList | string | the font list available on Android

```js
RNPdftron.getSystemFontList().then((fontList) => {
  console.log("OS font list:", fontList);
});
```

### clearRubberStampCache
Clear the information and bitmap cache for rubber stamps (Android only).
This is typically useful when the content of rubber stamps has been changed in the viewer.

Returns a promise.

```js
RNPdftron.clearRubberStampCache().then(() => {
  console.log("Rubber stamp cache cleared");
});
```

### clearSavedViewerState
Clear the saved view state such as page number, zoom location etc. (Android only).
This is typically useful when `DocumentView` is in a sub-navigation component and state-saving is not desired across sessions.

Returns a promise.

```js
RNPdftron.clearSavedViewerState().then(() => {
  console.log("Viewer state cleared");
});
```

### encryptDocument
Encrypts (password-protect) a document (must be a PDF). **Note**: This function does not lock the document it cannot be used it while the document is opened in the viewer.

Parameters:

Name | Type | Description
--- | --- | ---
file path | string | the local file path to the file
password | string | the password you would like to set
current password | string | the current password, use empty string if no password

Returns a promise.

Example:

```js
RNPdftron.encryptDocument("/sdcard/Download/new.pdf", "1111", "").then(() => {
  console.log("done password");
});
```

### pdfFromOffice
Generates a PDF from an Office document.

Parameters:

Name | Type | Description
--- | --- | ---
docxPath | string | the local file path to the Office file

Optional Parameters: 

Name | Type | Description
--- | --- | ---
applyPageBreaksToSheet | boolean | Whether we should split Excel workheets into pages so that the output resembles print output.
displayChangeTracking | boolean | If this option is true, will display office change tracking markup present in the document (i.e, red strikethrough of deleted content and underlining of new content).
excelDefaultCellBorderWidth | double | Cell border width for table cells that would normally be drawn with no border.
excelMaxAllowedCellCount | int | Conversion will throw an exception if the number of cells in a Microsoft Excel document is above the set MaxAllowedCellCount. 
locale | string | ISO 639-1 code of the current system locale. For example: 'en-US', 'ar-SA', 'de-DE', etc.

Returns a Promise.

Promise Parameters:

Name | Type | Description
--- | --- | ---
resultPdfPath | string | the local file path to the generated PDF 

The user is responsible for cleaning up the temporary file that is generated.

Example:

```js
// With options
RNPdftron.pdfFromOffice("/sdcard/Download/red.xlsx", 
  {
    applyPageBreaksToSheet: true, 
    displayChangeTracking: true, 
    excelDefaultCellBorderWidth: 1, 
    excelMaxAllowedCellCount: 250000, 
    locale: 'en-US'
  })
.then((resultPdfPath) => {
  console.log(resultPdfPath);
});

// Without options
RNPdftron.pdfFromOffice("/sdcard/Download/red.xlsx", null).then((resultPdfPath) => {
  console.log(resultPdfPath);
});
```

### pdfFromOfficeTemplate
Generates a PDF using a template in the form of an Office document and replacement data in the form of a JSON object.
For more information please see our [template guide](https://www.pdftron.com/documentation/core/guides/generate-via-template/).

Parameters:

Name | Type | Description
--- | --- | ---
docxPath | string | the local file path to the template file
json | object | the replacement data in the form of a JSON object

Returns a Promise.

Promise Parameters:

Name | Type | Description
--- | --- | ---
resultPdfPath | string | the local file path to the generated PDF 

The user is responsible for cleaning up the temporary file that is generated.

Example:

```js
RNPdftron.pdfFromOfficeTemplate("/sdcard/Download/red.docx", json).then((resultPdfPath) => {
  console.log(resultPdfPath);
});
```

#### exportAsImage
Export a PDF page to an image format defined in [`Config.ExportFormat`](./src/Config/Config.ts). 

Unlike DocumentView.exportAsImage, this method is static and should only be called *before* a `DocumentView` instance has been created or else unexpected behaviour can occur. This method also takes a local file path to the desired PDF.

Parameters:

Name | Type | Description
--- | --- | ---
pageNumber | int | the page to be converted; if the value does not refer to a valid page number, the file path will be undefined
dpi | double | the output image resolution
exportFormat | string | one of [`Config.ExportFormat`](./src/Config/Config.ts) constants
filePath | string | local file path to pdf
transparent | boolean | (only relevant when exported as PNG) whether the background of the image is transparent or the color of the PDF page (typically white)

Returns a Promise.

Name | Type | Description
--- | --- | ---
resultImagePath | string | the temp path of the created image, user is responsible for clean up the cache

```js
RNPdftron.exportAsImage(1, 92, Config.ExportFormat.BMP, "/sdcard/Download/red.pdf", false).then((resultImagePath) => {
  console.log('export', resultImagePath);
});
```

## DocumentView - Props

A React component for displaying documents of different types such as PDF, docx, pptx, xlsx and various image formats.

### Open a Document

#### document
string, required

The path or url to the document.

Example:

```js
<DocumentView
  document={'https://pdftron.s3.amazonaws.com/downloads/pl/PDFTRON_about.pdf'}
/>
```

#### source
string 

The path or url to the document. Wonday compatibility API.

Example:

```js
<DocumentView
  source={'https://pdftron.s3.amazonaws.com/downloads/pl/PDFTRON_about.pdf'}
/>
```

#### password
string, optional

The password of the document, if any.

Example:

```js
<DocumentView
  password={'password'}
/>
```

#### isBase64String
bool, optional, defaults to false

If true, [`document`](#document) prop will be treated as a base64 string. If it is not the base64 string of a pdf file, [`base64FileExtension`](#base64FileExtension) is required. 

When viewing a document initialized with a base64 string (i.e. a memory buffer), a temporary file is created on Android and iOS.

```js
<DocumentView
  isBase64String={true}
  document={'...'} // base 64 string
/>
```

#### base64FileExtension
string, required if using base64 string of a non-pdf file, defaults to ".pdf"

The file extension for the base64 string in [`document`](#document), if [`isBase64String`](#isBase64String) is true.

```js
<DocumentView
  isBase64String={true}
  document={'...'} // base 64 string
  base64FileExtension={'.jpeg'}
/>
```

#### documentExtension
string, optional, defaults to the extension in the [`document`](#document) prop. 

Used for specifying the extension of the document to be loaded. 

```js
<DocumentView
  document={"https://pdftron.s3.amazonaws.com/pdfInDisguise.png"}
  documentExtension={"pdf"}
/>
```

#### customHeaders
object, optional

Defines custom headers to use with HTTP/HTTPS requests.

```js
<DocumentView
  customHeaders={{headerKey: 'headerValue'}}
/>
```

#### readOnly
bool, optional, defaults to false

Defines whether the viewer is read-only. If true, the UI will not allow the user to change the document.

```js
<DocumentView
  readOnly={true}
/>
```
#### defaultEraserType
one of the [`Config.EraserType`](./src/Config/Config.ts) constants, optional

Sets the default eraser tool type. Value only applied after a clean install.

Eraser Type | Description
--- | ---
`annotationEraser` | Erases everything as an object; if you touch ink, the entire object is erased.
`hybrideEraser` | Erases ink by pixel, but erases other annotation types as objects.
`inkEraser` | Erases ink by pixel only. Android only.

```js
<DocumentView
  defaultEraserType={Config.EraserType.hybrideEraser}
/>
```

#### exportPath
string, optional

Sets the folder path for all save options, this defaults to the app cache path. Android only.
Example:

```js
<DocumentView
  exportPath="/data/data/com.example/cache/test"
/>
```

#### openUrlPath
string, optional

Sets the cache folder used to cache PDF files opened using a http/https link, this defaults to the app cache path. Android only.
Example:

```js
<DocumentView
  openUrlPath="/data/data/com.example/cache/test"
/>
```

#### saveStateEnabled
bool, optional, default to true

Sets whether to remember the last visited page and zoom for a document if it gets opened again.

On iOS this prop only applies to local documents and saves the last visited page. The zoom is not saved.

On Android the zoom and last visited page are saved for both local and remote documents.

Example:

```js
<DocumentView
  saveStateEnabled={false}
/>
```

#### openSavedCopyInNewTab
bool, optional, default to true, Android only.

Sets whether the new saved file should open after saving.
Example:

```js
<DocumentView
  openSavedCopyInNewTab={false}
/>
```

#### onDocumentLoaded
function, optional

This function is called when the document finishes loading.

Parameters:

Name | Type | Description
--- | --- | ---
path | string | File path that the document has been saved to

```js
<DocumentView
  onDocumentLoaded = {(path) => { 
    console.log('The document has finished loading:', path); 
  }}
/>
```

#### onLoadComplete
function, optional

This function is called when the document finishes loading.

Parameters:

Name | Type | Description
--- | --- | ---
path | string | File path that the document has been saved to

```js
<DocumentView
  onLoadComplete = {(path) => { 
    console.log('The document has finished loading:', path); 
  }}
/>
```
#### onDocumentError
function, optional

This function is called when document opening encounters an error.

Parameters:

Name | Type | Description
--- | --- | ---
error | string | Error message produced

```js
<DocumentView
  onDocumentError = {(error) => { 
    console.log('Error occured during document opening:', error); 
  }}
/>
```

#### onError
function, optional

This function is called when document opening encounters an error.

Parameters:

Name | Type | Description
--- | --- | ---
error | string | Error message produced

```js
<DocumentView
  onError = {(error) => { 
    console.log('Error occured during document opening:', error); 
  }}
/>
```
### UI Customization

#### disabledElements
array of [`Config.Buttons`](./src/Config/Config.ts) constants, optional, defaults to none

Defines buttons to be disabled for the viewer.

```js
<DocumentView
  disabledElements={[Config.Buttons.userBookmarkListButton]}
/>
```

#### disabledTools
array of [`Config.Tools`](./src/Config/Config.ts) constants, optional, defaults to none

Defines tools to be disabled for the viewer.

```js
<DocumentView
  disabledTools={[Config.Tools.annotationCreateLine, Config.Tools.annotationCreateRectangle]}
/>
```

#### onToolChanged
function, optional

This function is called when the current tool changes to a new tool

Parameters:

Name | Type | Description
--- | --- | ---
previousTool | string | the previous tool (one of the [`Config.Tools`](./src/Config/Config.ts) constants or "unknown tool"), representing the tool before change
tool | string | the current tool (one of the [`Config.Tools`](./src/Config/Config.ts) constants or "unknown tool"), representing the current tool

```js
<DocumentView
  onToolChanged = {({previousTool, tool}) => {
    console.log('Tool has been changed from', previousTool, 'to', tool);
  }}
/>
```

#### rememberLastUsedTool
boolean, optional, defaults to true, Android only

Defines whether the last tool used in the current viewer session will be the tool selected upon starting a new viewer session.

Example:

```js
<DocumentView
  rememberLastUsedTool={false}
/>
```

#### leadingNavButtonIcon
string, optional

The file name of the icon to be used for the leading navigation button. The button will use the specified icon if it is valid, and the default icon otherwise.

Example:

```js
<DocumentView
  leadingNavButtonIcon={Platform.OS === 'ios' ? 'ic_close_black_24px.png' : 'ic_arrow_back_white_24dp'}
/>
```

**Note**: to add the image file to your application, please follow the steps below:

##### Android
1. Add the image resource to the drawable directory in [`example/android/app/src/main/res`](./example/android/app/src/main/res). For details about supported file types and potential compression, check out [here](https://developer.android.com/guide/topics/graphics/drawables#drawables-from-images).

<img alt='demo-android' src='https://pdftron.s3.amazonaws.com/custom/websitefiles/react-native/android_add_resources.png'/>

2. Now you can use the image in the viewer. For example, if you add `button_close.png` to drawable, you could use `'button_close'` in leadingNavButtonIcon.

##### iOS
1. After pods has been installed, open the `.xcworkspace` file for this application in Xcode (in this case, it's [`example.xcworkspace`](./example/ios/example.xcworkspace)), and navigate through the list below. This would allow you to add resources, in this case, an image, to your project.
- "Project navigator"
- "example" (or the app name)
- "Build Phases"
- "Copy Bundle Resources"
- "+".

<img alt='demo-ios' src='https://pdftron.s3.amazonaws.com/custom/websitefiles/react-native/ios_add_resources.png'/>

2. Now you can use the image in the viewer. For example, if you add `button_open.png` to the bundle, you could use `'button_open.png'` in leadingNavButtonIcon.


#### showLeadingNavButton
bool, optional, defaults to true

Defines whether to show the leading navigation button.

```js
<DocumentView
  showLeadingNavButton={true}
/>
```

#### onLeadingNavButtonPressed
function, optional

This function is called when the leading navigation button is pressed.

```js
<DocumentView
  onLeadingNavButtonPressed = {() => {
    console.log('The leading nav has been pressed');
  }}
/>
```

#### overflowMenuButtonIcon
String, optional

The file name of the icon to be used as the overflow menu button. The button will use the specified icon if it is valid, and the default icon otherwise.

**Note**: to add the image file to your application, follow the steps under the Note section of [`leadingNavButtonIcon`](#leadingNavButtonIcon).

Example:

```js
<DocumentView
  overflowMenuButtonIcon={Platform.OS === 'ios' ? 'ic_close_black_24px.png' : 'ic_arrow_back_white_24dp'}
/>
```

#### documentSliderEnabled
bool, optional, defaults to true

Defines whether the document slider of the viewer is enabled.

```js
<DocumentView
  documentSliderEnabled={false}
/>
```

#### hideViewModeItems
array of [`Config.ViewModePickerItem`](./src/Config/Config.ts) constants, optional, defaults to none.

Defines view mode items to be hidden in the view mode dialog.

```js
<DocumentView
  hideViewModeItems={[
    Config.ViewModePickerItem.Crop,
    Config.ViewModePickerItem.Rotation,
    Config.ViewModePickerItem.ColorMode,
    Config.ViewModePickerItem.ReaderModeSettings,
  ]}
/>
```

#### tabletLayoutEnabled
bool, optional, defaults to true

Defines whether the tablet layout should be used on tablets. Otherwise uses the same layout as phones. Android only.

```js
<DocumentView
  tabletLayoutEnabled={true}
/>
```

#### downloadDialogEnabled
bool, optional, defaults to true

Defines whether the download dialog should be shown. Android only.

```js
<DocumentView
  downloadDialogEnabled={true}
/>
```

### Toolbar Customization

#### topToolbarEnabled
bool, optional, defaults to true

Deprecated. Use [`hideTopAppNavBar`](#hideTopAppNavBar) prop instead.

#### bottomToolbarEnabled
bool, optional, defaults to true

Defines whether the bottom toolbar of the viewer is enabled.

```js
<DocumentView
  bottomToolbarEnabled={false}
/>
```

#### hidePresetBar
bool, optional, defaults to false

Defines whether preset bar is hidden or not

```js
<DocumentView
  hidePresetBar={true}
/>
```

#### annotationToolbars
array of [`Config.DefaultToolbars`](./src/Config/Config.ts) constants or custom toolbar objects, optional, defaults to none

Defines custom toolbars. If passed in, the default toolbars will no longer appear. When indicating the icon of a custom toolbar item, ensure that the resource for either Android or iOS exists.
It is possible to mix and match with default toolbars. See example below:

```js
const myToolItem = {
  [Config.CustomToolItemKey.Id]: 'add_page',
  [Config.CustomToolItemKey.Name]: 'Add page',
  // An example of custom Android icon:
  [Config.CustomToolItemKey.Icon]: 'ic_add_blank_page_white', 
  // An example of custom iOS icon:
  //[Config.CustomToolItemKey.Icon]: 'pencil.circle', 
};

const myToolbar = {
  [Config.CustomToolbarKey.Id]: 'myToolbar',
  [Config.CustomToolbarKey.Name]: 'myToolbar',
  [Config.CustomToolbarKey.Icon]: Config.ToolbarIcons.FillAndSign,
  [Config.CustomToolbarKey.Items]: [Config.Tools.annotationCreateArrow, Config.Tools.annotationCreateCallout, myToolItem, Config.Buttons.undo]
};

<DocumentView
  annotationToolbars={[Config.DefaultToolbars.Annotate, myToolbar]}
/>
```

#### onCurrentToolbarChanged
function, optional

This function is called when the current toolbar has changed.

Parameters:

Name | Type | Description
--- | --- | ---
toolbar | string | The current toolbar. One of the [`Config.DefaultToolbars`](./src/Config/Config.ts) constants or the `id` of a custom toolbar object.

```js
<DocumentView
  onCurrentToolbarChanged = {({toolbar}) => {
    console.log('toolbar changed to: ' + toolbar);
  }}
/>
```

#### onAnnotationToolbarItemPress
function, optional

This function is called when a custom toolbar tool item is clicked

Parameters:

Name | Type | Description
--- | --- | ---
id | string | the `Config.CustomToolItemKey.Id` defined in the tool

```js
<DocumentView
  onAnnotationToolbarItemPress = {({id}) => {
    console.log('toolbar item press: ' + id);
  }}
/>

```

#### hideDefaultAnnotationToolbars
array of [`Config.DefaultToolbars`](./src/Config/Config.ts) constants, optional, defaults to none

Defines which default annotation toolbars should be hidden. Note that this prop should be used when [`annotationToolbars`](#annotationToolbars) is not defined.

```js
<DocumentView
  hideDefaultAnnotationToolbars={[Config.DefaultToolbars.Annotate, Config.DefaultToolbars.Favorite]}
/>
```

#### hideThumbnailsViewItems
array of [`Config.ThumbnailsViewItem`](./src/Config/Config.ts) constants, optional, defaults to none

Defines which default thumbnail view items should be hidden.
Note: InsertFromPhoto item is for iOS only
On Android, photo and camera are both included in InsertFromImage

```js
<DocumentView
  hideThumbnailsViewItems={[Config.ThumbnailsViewItem.InsertPages, Config.ThumbnailsViewItem.ExportPages]}
/>
```
#### hideAnnotationToolbarSwitcher
bool, optional, defaults to false

Defines whether to show the toolbar switcher in the top toolbar.

```js
<DocumentView
  hideAnnotationToolbarSwitcher={false}
/>
```

#### initialToolbar
one of the [`Config.DefaultToolbars`](./src/Config/Config.ts) constants or the `id` of a custom toolbar object, optional, defaults to none

Defines which [`annotationToolbar`](#annotationToolbars) should be selected when the document is opened.

```js
<DocumentView
  initialToolbar={Config.DefaultToolbars.Draw}
/>
```

#### hideTopToolbars
bool, optional, defaults to false

Defines whether to hide both the top app nav bar and the annotation toolbar.

```js
<DocumentView
  hideTopToolbars={false}
/>
```

#### hideTopAppNavBar
bool, optional, defaults to false

Defines whether to hide the top navigation app bar.

```js
<DocumentView
  hideTopAppNavBar={true}
/>
```

#### hideToolbarsOnTap
bool, optional, defaults to true

Defines whether an unhandled tap in the viewer should toggle the visibility of the top and bottom toolbars. When false, the top and bottom toolbar visibility will not be toggled and the page content will fit between the bars, if any.

```js
<DocumentView
  hideToolbarsOnTap={false}
/>
```

#### hideToolbarsOnAppear
bool, optional, defaults to false, android only

Defines whether the toolbars will be gone at startup.

Android 

```js
<DocumentView
  hideToolbarsOnAppear={true}
/>
```

#### topAppNavBarRightBar
array of [`Config.Buttons`](./src/Config/Config.ts) constants, optional, only the tabs, search, view mode, thumbnails, outline, undo, share, reflow, edit pages, save copy, print, file attachment, layers, digital signatures and close buttons are supported on Android

Customizes the right bar section of the top app nav bar. If passed in, the default right bar section will not be used.

```js
<DocumentView
  topAppNavBarRightBar={[Config.Buttons.reflowButton, Config.Buttons.outlineListButton]}
/>
```

#### bottomToolbar
array of [`Config.Buttons`](./src/Config/Config.ts) constants, optional, only the outline list, thumbnail list, share, view mode, search, and reflow buttons are supported on Android

Defines a custom bottom toolbar. If passed in, the default bottom toolbar will not be used.

```js
<DocumentView
  bottomToolbar={[Config.Buttons.reflowButton, Config.Buttons.outlineListButton]}
/>
```

#### padStatusBar
bool, optional, defaults to false, android only

Defines whether the viewer will add padding to take account of the system status bar.

```js
<DocumentView
  padStatusBar={true}
/>
```

#### overrideToolbarButtonBehavior
array of [`Config.Buttons`](./src/Config/Config.ts) constants, optional, defaults to none

Defines the option buttons in the top app nav bar or the bottom toolbar that will skip default behavior when pressed.
They will still be displayed in the toolbar, and the function [`onToolbarButtonPress`](#ontoolbarbuttonpress) will be called where custom behavior can be implemented.

```js
<DocumentView
  overrideToolbarButtonBehavior={[Config.Buttons.shareButton, Config.Buttons.searchButton]}
  onToolbarButtonPress={({id}) => {
    if (id === Config.Buttons.shareButton) {
      console.log('Share button pressed');
    } else if (id === Config.Buttons.searchButton) {
      console.log('Search button pressed');
    }
  }}
/>
```

#### onToolbarButtonPress
function, optional

This function is called when a toolbar item passed in to [`overrideToolbarButtonBehavior`](#overridetoolbarbuttonbehavior) is pressed.

Parameters:

Name | Type | Description
--- | --- | ---
id | string | one of [`Config.Buttons`](./src/Config/Config.ts) constants representing the item that has been pressed

```js
<DocumentView
  overrideToolbarButtonBehavior={[Config.Buttons.shareButton, Config.Buttons.searchButton]}
  onToolbarButtonPress={({id}) => {
    if (id === Config.Buttons.shareButton) {
      console.log('Share button pressed');
    } else if (id === Config.Buttons.searchButton) {
      console.log('Search button pressed');
    }
  }}
/>
```

### Layout

#### fitMode
one of the [`Config.FitMode`](./src/Config/Config.ts) constants, optional, default value is `Config.FitMode.FitWidth`

Defines the fit mode (default zoom level) of the viewer.

```js
<DocumentView
  fitMode={Config.FitMode.FitPage}
/>
```

#### fitPolicy

Defines the fit mode (default zoom level) of the viewer.
Parameters:

Mode | Value | Description
--- | --- | ---
fitPage (default) | 0 | fits the whole page
fit width | 1 | fits page using width
fit hieght | 2 | fits page using height

```js
<DocumentView
  fitPolicy={2}
/>
```

#### maintainZoomEnabled
bool, optional, defaults to true, Android only.

Defines whether the viewer should maintain zoom level when flipping pages.

```js
<DocumentView
  maintainZoomEnabled={true}
/>
```

#### layoutMode
one of the [`Config.LayoutMode`](./src/Config/Config.ts) constants, optional, default value is `Config.LayoutMode.Continuous`

Defines the layout mode of the viewer.

```js
<DocumentView
  layoutMode={Config.LayoutMode.FacingContinuous}
/>
```

#### onLayoutChanged
function, optional

This function is called when the layout of the viewer has been changed.

```js
<DocumentView
  onLayoutChanged = {() => {
    console.log('Layout has been updated.');
  }}
/>
```

### Page

#### initialPageNumber
number, optional

Defines the initial page number that viewer displays when the document is opened. Note that page numbers are 1-indexed.

```js
<DocumentView
  initialPageNumber={5}
/>
```

#### page
number, optional

Defines the initial page number that viewer displays when the document is opened. Note that page numbers are 1-indexed.

```js
<DocumentView
  page={5}
/>
```

#### pageNumber
number, optional

Defines the currently displayed page number. Different from [`initialPageNumber`](#initialPageNumber), changing this prop value at runtime will change the page accordingly.

```js
<DocumentView
  pageNumber={5}
/>
```

#### pageChangeOnTap
bool, optional, defaults to true

Defines whether the viewer should change pages when the user taps the edge of a page, when the viewer is in a horizontal viewing mode.

```js
<DocumentView
  pageChangeOnTap={true}
/>
```

#### pageIndicatorEnabled
bool, optional, defaults to true

Defines whether to show the page indicator for the viewer.

```js
<DocumentView
  pageIndicatorEnabled={true}
/>
```

#### keyboardShortcutsEnabled
bool, optional, defaults to true

Defines whether the keyboard shortcuts of the viewer are enabled.

```js
<DocumentView
  keyboardShortcutsEnabled={false}
/>
```

#### onPageChanged
function, optional

This function is called when the page number has been changed.

Parameters:

Name | Type | Description
--- | --- | ---
previousPageNumber | int | the previous page number
pageNumber | int | the current page number

```js
<DocumentView
  onPageChanged = {({previousPageNumber, pageNumber}) => {
    console.log('Page number changes from', previousPageNumber, 'to', pageNumber);
  }}
/>
```

#### onPageMoved
function, optional

This function is called when a page has been moved in the document.

Parameters:

Name | Type | Description
--- | --- | ---
previousPageNumber | int | the previous page number
pageNumber | int | the current page number

```js
<DocumentView
  onPageMoved = {({previousPageNumber, pageNumber}) => {
    console.log('Page moved from', previousPageNumber, 'to', pageNumber);
  }}
/>
```

#### onPagesAdded
function, optional

This function is called when pages are added to the document.

Parameters:

Name | Type | Description
--- | --- | ---
pageNumbers | array | An array of the page numbers that were added to the document

```js
<DocumentView
  onPagesAdded = {({pageNumbers}) => {
    console.log('Pages added:', pageNumbers);
  }}
/>
```

#### onPagesRotated
function, optional

This function is called when pages are rotated.

Parameters:

Name | Type | Description
--- | --- | ---
pageNumbers | array | An array of the page numbers that were rotated

```js
<DocumentView
  onPagesRotated = {({pageNumbers}) => {
    console.log('Pages rotated:', pageNumbers);
  }}
/>
```

#### onPagesRemoved
function, optional

This function is called when pages are removed from the document.

Parameters:

Name | Type | Description
--- | --- | ---
pageNumbers | array | An array of the page numbers that were removed from the document

```js
<DocumentView
  onPagesRemoved = {({pageNumbers}) => {
    console.log('Pages removed:', pageNumbers);
  }}
/>
```

### Zoom

#### zoom
double, optional

This prop defines the zoom of the document

```js
<DocumentView
  zoom={2.0}
/>
```

#### scale
double, optional

This prop defines the zoom of the document.
Same as zoom. Wonday compatibility API.

```js
<DocumentView
  scale={2.0}
/>
```

#### onZoomChanged
function, optional

This function is called when the zoom scale has been changed.

Parameters:

Name | Type | Description
--- | --- | ---
zoom | double | the current zoom ratio of the document

```js
<DocumentView
  onZoomChanged = {(zoom) => {
    console.log('Current zoom ratio is', zoom);
  }}
/>
```
#### onScaleChanged
function, optional

This function is called when the zoom scale has been changed.

Parameters:

Name | Type | Description
--- | --- | ---
zoom | double | the current zoom ratio of the document

```js
<DocumentView
  onScaleChanged = {(scale) => {
    console.log('Current scale ratio is', scale);
  }}
/>
```

#### onZoomFinished
function, optional

This function is called when a zooming has been finished. For example, if zoom via gesture, this is called on gesture release.

Parameters:

Name | Type | Description
--- | --- | ---
zoom | double | the current zoom ratio of the document

```js
<DocumentView
  onZoomFinished = {(zoom) => {
    console.log('Current zoom ratio is', zoom);
  }}
```

### Scroll

#### horizontalScrollPos
number, optional

Defines the horizontal scroll position in the current document viewer.

```js
<DocumentView
  horizontalScrollPos={50}
/>
```

#### verticalScrollPos
number, optional

Defines the vertical scroll position in the current document viewer.

```js
<DocumentView
  verticalScrollPos={50}
/>
```

#### onScrollChanged
function, optional

This function is called when the scroll position has been changed.

Parameters:

Name | Type | Description
--- | --- | ---
horizontal | number | the horizontal position of the scroll
vertical | number | the vertical position of the scroll

```js
<DocumentView
  onScrollChanged = {({horizontal, vertical}) => {
    console.log('Current scroll position is', horizontal, 'horizontally, and', vertical, 'vertically.');
  }}
```

#### hideScrollbars
bool, optional, iOS only, defaults to false

Determines whether scrollbars will be hidden on the viewer.

```js
<DocumentView
  hideScrollbars={true}
/>
```

### Reflow

#### imageInReflowEnabled
bool, optional, defaults to true, will be available on iOS in version 9.1.2 and greater

Whether to show images in reflow mode. 

```js
<DocumentView
  imageInReflowEnabled={false}
/>
```

#### reflowOrientation
one of the [`Config.ReflowOrientation`](./src/Config/Config.ts) constants, optional, defaults to the viewer's scroll direction.

Sets the scrolling direction of the reflow control.

```js
<DocumentView
  reflowOrientation={Config.ReflowOrientation.Vertical} 
/>
```

### Annotation Menu

#### hideAnnotationMenu
array of [`Config.Tools`](./src/Config/Config.ts) constants, optional, defaults to none

Defines annotation types that will not show in the annotation (long-press) menu.

```js
<DocumentView
  hideAnnotationMenu={[Config.Tools.annotationCreateArrow, Config.Tools.annotationEraserTool]}
/>
```

#### annotationMenuItems
array of [`Config.AnnotationMenu`](./src/Config/Config.ts) constants, optional, default contains all the items

Defines the menu items that can show when an annotation is selected.

```js
<DocumentView
  annotationMenuItems={[Config.AnnotationMenu.search, Config.AnnotationMenu.share]}
/>
```

#### overrideAnnotationMenuBehavior
array of [`Config.AnnotationMenu`](./src/Config/Config.ts) constants, optional, defaults to none

Defines the menu items that will skip default behavior when pressed. They will still be displayed in the annotation menu, and the function [`onAnnotationMenuPress`](#onAnnotationMenuPress) will be called where custom behavior can be implemented.

```js
<DocumentView
  overrideAnnotationMenuBehavior={[Config.AnnotationMenu.copy]}
/>
```

#### onAnnotationMenuPress
function, optional

This function is called when an annotation menu item passed in to [`overrideAnnotationMenuBehavior`](#overrideAnnotationMenuBehavior) is pressed.

Parameters:

Name | Type | Description
--- | --- | ---
annotationMenu | string | One of [`Config.AnnotationMenu`](./src/Config/Config.ts) constants, representing which item has been pressed
annotations | array | An array of `{id: string, pageNumber: number, type: string, screenRect: object, pageRect: object}` objects.<br><br>`id` is the annotation identifier and `type` is one of the [`Config.Tools`](./src/Config/Config.ts) constants. `screenRect` was formerly called `rect`. Both rects are represented with `{x1: number, y1: number, x2: number, y2: number, width: number, height: number}` objects.

```js
<DocumentView
  onAnnotationMenuPress = {({annotationMenu, annotations}) => {
    console.log('Annotation menu item', annotationMenu, 'has been pressed');
    annotations.forEach(annotation => {
      console.log('The id of selected annotation is', annotation.id);
      console.log('The page number of selected annotation is', annotation.pageNumber);
      console.log('The type of selected annotation is', annotation.type);
      console.log('The screenRect of selected annotation is', annotation.screenRect);
      console.log('The pageRect of selected annotation is', annotation.pageRect);
    });
  }}
/>
```

### Long Press Menu

#### longPressMenuEnabled
bool, optional, defaults to true

Defines whether to show the popup menu of options when the user long presses on text or blank space on the document.

```js
<DocumentView
  longPressMenuEnabled={true}
/>
```

#### longPressMenuItems
array of [`Config.LongPressMenu`](./src/Config/Config.ts) constants, optional, default contains all the items

Defines menu items that can show when long press on text or blank space.

```js
<DocumentView
  longPressMenuItems={[Config.LongPressMenu.copy, Config.LongPressMenu.read]}
/>
```

#### overrideLongPressMenuBehavior
array of [`Config.LongPressMenu`](./src/Config/Config.ts) constants, optional, defaults to none

Defines the menu items on long press that will skip default behavior when pressed. They will still be displayed in the long press menu, and the function [`onLongPressMenuPress`](#onLongPressMenuPress) will be called where custom behavior can be implemented.

```js
<DocumentView
  overrideLongPressMenuBehavior={[Config.LongPressMenu.search]}
/>
```

#### onLongPressMenuPress
function, optional

This function is called if the pressed long press menu item is passed in to [`overrideLongPressMenuBehavior`](#overrideLongPressMenuBehavior)

Parameters:

Name | Type | Description
--- | --- | ---
longPressMenu | string | One of [`Config.LongPressMenu`](./src/Config/Config.ts) constants, representing which item has been pressed
longPressText | string | the selected text if pressed on text, empty otherwise

```js
<DocumentView
  onLongPressMenuPress = {({longPressMenu, longPressText}) => {
    console.log('Long press menu item', longPressMenu, 'has been pressed');
    if (longPressText !== '') {
      console.log('The selected text is', longPressText);
    }
  }}
/>
```

### Custom Behavior

#### overrideBehavior
array of [`Config.Actions`](./src/Config/Config.ts) constants, optional, defaults to none

Defines actions that will skip default behavior, such as external link click. The function [`onBehaviorActivated`](#onBehaviorActivated) will be called where custom behavior can be implemented, whenever the defined actions occur.

```js
<DocumentView
  overrideBehavior={[Config.Actions.linkPress]}
/>
```

#### onBehaviorActivated
function, optional

This function is called if the activated behavior is passed in to [`overrideBehavior`](#overrideBehavior)

Parameters:

Name | Type | Description
--- | --- | ---
action | string | One of [`Config.Actions`](./src/Config/Config.ts) constants, representing which action has been activated
data | object | A JSON object that varies depending on the action

Data param table:

Action | Data param
--- | ---
[`Config.Actions.linkPress`](./src/Config/Config.ts) | `{url: string}`
[`Config.Actions.stickyNoteShowPopUp`](./src/Config/Config.ts) | `{id: string, pageNumber: number, type: string, screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`. Type is one of the [`Config.Tools`](./src/Config/Config.ts) constants. `screenRect` was formerly called `rect`.

```js
<DocumentView
  onBehaviorActivated = {({action, data}) => {
    console.log('Activated action is', action);
    if (action === Config.Actions.linkPress) {
      console.log('The external link pressed is', data.url);
    } else if (action === Config.Actions.stickyNoteShowPopUp) {
      console.log('Sticky note has been activated, but it would not show a pop up window.');
    }
  }}
/>
```

### Multi-tab

#### multiTabEnabled
bool, optional, defaults to false

Defines whether viewer will use tabs in order to have more than one document open simultaneously (like a web browser). Changing the [`document`](#document) prop value will cause a new tab to be opened with the associated file.

```js
<DocumentView
  multiTabEnabled={true}
/>
```

#### tabTitle
string, optional, default is the file name

Set the tab title if [`multiTabEnabled`](#multiTabEnabled) is true.

```js
<DocumentView
  multiTabEnabled={true}
  tabTitle={'tab1'}
/>
```

#### maxTabCount
number, optional, defaults to unlimited

Sets the limit on the maximum number of tabs that the viewer could have at a time. Open more documents after reaching this limit will overwrite the old tabs.

```js
<DocumentView
  multiTabEnabled={true}
  maxTabCount={5}
/>
```

#### onTabChanged
function, optional

The function is activated when a tab is changed. 

Please note that this API is meant for tab-specific changes. If you would like to know when the document finishes loading instead, see the [`onDocumentLoaded`](#onDocumentLoaded) event.

Parameters:

Name | Type | Description
--- | --- | ---
currentTab | string | The file path of current tab's document


```js
<DocumentView
  multiTabEnabled={true}
  onTabChanged={({currentTab}) => {
    console.log("The current tab is ", currentTab);
  }}
/>
```

### Collaboration

#### collabEnabled
bool, optional, defaults to false

Defines whether to enable realtime collaboration. If true then `currentUser` must be set as well for collaboration mode to work. Feature set may vary between local and collaboration mode.

```js
<DocumentView
  collabEnabled={true}
  currentUser={'Pdftron'}
/>
```

#### currentUser
string, required if [`collabEnabled`](#collabEnabled) is set to true

Defines the current user. Created annotations will have their title (author) set to this string.

```js
<DocumentView
  collabEnabled={true}
  currentUser={'Pdftron'}
/>
```

#### currentUserName
string, optional

Defines the current user name. Will set the user name only if [`collabEnabled`](#collabEnabled) is true and [`currentUser`](#currentUser) is defined. This should be used only if you want the user's display name to be different than the annotation's title/author (in the case that `currentUser` is an ID rather than a human-friendly name.)

```js
<DocumentView
  collabEnabled={true}
  currentUser={'Pdftron'}
  currentUserName={'Hello_World'}
/>
```

#### annotationManagerEditMode
one of the [`Config.AnnotationManagerEditMode`](./src/Config/Config.js) constants, optional, default value is `Config.AnnotationManagerEditMode.Own`

Sets annotation manager edit mode when [`collabEnabled`](#collabEnabled) is true.

Mode | Description
--- | ---
`Config.AnnotationManagerEditMode.Own` | In this mode, you can edit only your own changes 
`Config.AnnotationManagerEditMode.All` | In this mode, you can edit everyone's changes 

```js
<DocumentView
  collabEnabled={true}
  currentUser={'Pdftron'}
  annotationManagerEditMode={Config.AnnotationManagerEditMode.All}
/>
```

#### annotationManagerUndoMode
one of the [`Config.AnnotationManagerUndoMode`](./src/Config/Config.js) constants, optional, default value is `Config.AnnotationManagerUndoMode.Own`

Sets annotation manager undo mode when [`collabEnabled`](#collabEnabled) is true.

Mode | Description
--- | ---
`Config.AnnotationManagerUndoMode.Own` | In this mode, you can undo only your own changes 
`Config.AnnotationManagerUndoMode.All` | In this mode, you can undo everyone's changes 

```js
<DocumentView
  collabEnabled={true}
  currentUser={'Pdftron'}
  annotationManagerUndoMode={Config.AnnotationManagerUndoMode.All}
/>
```

#### replyReviewStateEnabled
boolean, optional, defaults to true

Defines whether to show an annotation's reply review state.

```js
<DocumentView
  collabEnabled={true}
  currentUser={'Pdftron'}
  replyReviewStateEnabled={true}
/>
```

### Annotations

#### annotationPermissionCheckEnabled
bool, optional, defaults to false

Defines whether an annotation's permission flags will be respected when it is selected. For example, a locked annotation can not be resized or moved.

```js
<DocumentView
  annotationPermissionCheckEnabled={true}
/>
```

#### annotationAuthor
string, optional

Defines the author name for all annotations created on the current document. Exported xfdfCommand will include this piece of information.

```js
<DocumentView
  annotationAuthor={'PDFTron'}
/>
```

#### continuousAnnotationEditing
bool, optional, defaults to true

If true, the active annotation creation tool will remain in the current annotation creation tool. Otherwise, it will revert to the "pan tool" after an annotation is created.

```js
<DocumentView
  continuousAnnotationEditing={true}
/>
```

#### inkMultiStrokeEnabled
bool, optional, defaults to true

If true, ink tool will use multi-stroke mode. Otherwise, each stroke is a new ink annotation.

```js
<DocumentView
  inkMultiStrokeEnabled={true}
/>
```

#### selectAnnotationAfterCreation
bool, optional, defaults to true

Defines whether an annotation is selected after it is created. On iOS, this functions for shape and text markup annotations only.

```js
<DocumentView
  selectAnnotationAfterCreation={true}
/>
```

#### onExportAnnotationCommand
function, optional

This function is called if a change has been made to annotations in the current document. Unlike [`onAnnotationChanged`](#onAnnotationChanged), this function has an XFDF command string as its parameter. If you are modifying or deleting multiple annotations, then on Android the function is only called once, and on iOS it is called for each annotation.


Parameters:

Name | Type | Description
--- | --- | ---
action | string | the action that occurred (add, delete, modify, undo, redo)
xfdfCommand | string | an xfdf string containing info about the edit
annotations | array | an array of annotation data. When collaboration is enabled data comes in the format `{id: string}`, otherwise the format is `{id: string, pageNumber: number, type: string}`. In both cases, the data represents the annotations that have been changed. `type` is one of the [`Config.Tools`](./src/Config/Config.ts) constants 

```js
<DocumentView
  onExportAnnotationCommand = {({action, xfdfCommand, annotations}) => {
    console.log('Annotation edit action is', action);
    console.log('The exported xfdfCommand is', xfdfCommand);
    annotations.forEach((annotation) => {
      console.log('Annotation id is', annotation.id);
      if (!this.state.collabEnabled) {
        console.log('Annotation pageNumber is', annotation.pageNumber);
        console.log('Annotation type is', annotation.type);
      }
    });
  }}
  collabEnabled={this.state.collabEnabled}
  currentUser={'Pdftron'}
/>
```

#### onAnnotationsSelected
function, optional

This function is called when an annotation(s) is selected.

Parameters:

Name | Type | Description
--- | --- | ---
annotations | array | array of annotation data in the format `{id: string, pageNumber: number, type: string, screenRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}, pageRect: {x1: number, y1: number, x2: number, y2: number, width: number, height: number}}`, representing the selected annotations. Type is one of the [`Config.Tools`](./src/Config/Config.ts) constants. `screenRect` was formerly called `rect`.

```js
<DocumentView
  onAnnotationsSelected = {({annotations}) => {
    annotations.forEach(annotation => {
      console.log('The id of selected annotation is', annotation.id);
      console.log('It is in page', annotation.pageNumber);
      console.log('Its type is', annotation.type);
    });
  }}
/>
```

#### onAnnotationChanged
function, optional

This function is called if a change has been made to an annotation(s) in the current document.

Note: When an annotation is flattened, it also gets deleted, so both [`onAnnotationChanged`](#onAnnotationChanged) and [`onAnnotationFlattened`](#onAnnotationFlattened) are called.

Parameters:

Name | Type | Description
--- | --- | ---
action | string | the action that occurred (add, delete, modify)
annotations | array | array of annotation data in the format `{id: string, pageNumber: number, type: string}`, representing the annotations that have been changed. `type` is one of the [`Config.Tools`](./src/Config/Config.ts) constants

```js
<DocumentView
  onAnnotationChanged = {({action, annotations}) => {
    console.log('Annotation edit action is', action);
    annotations.forEach(annotation => {
      console.log('The id of changed annotation is', annotation.id);
      console.log('It is in page', annotation.pageNumber);
      console.log('Its type is', annotation.type);
    });
  }}
/>
```

#### onAnnotationFlattened
function, optional

This function is called if an annotation(s) has been flattened in the current document.

Parameters:

Name | Type | Description
--- | --- | ---
annotations | array | array of annotation data in the format `{id: string, pageNumber: number, type: string}`, representing the annotations that have been changed. `type` is one of the [`Config.Tools`](./src/Config/Config.ts) constants. `id`s returned via the event listener can be null.

```js
<DocumentView
  onAnnotationFlattened={({annotations}) => {
    annotations.forEach(annotation => {
      console.log('The id of changed annotation is', annotation.id);
      console.log('It is in page', annotation.pageNumber);
      console.log('Its type is', annotation.type);
    });
  }}
/>
```

#### onFormFieldValueChanged
function, optional

This function is called if a change has been made to form field values. Additionally signatures type fields will have the fieldHasAppearance value defined.
The hasAppearance indicates whether the signature field was signed or not

Parameters:

Name | Type | Description
--- | --- | ---
fields | array | array of field data in the format `{fieldName: string, fieldType: string, fieldValue: any, fieldHasAppearance: boolean}`, representing the fields that have been changed

```js
<DocumentView
  onFormFieldValueChanged = {({fields}) => {
    fields.forEach(field => {
      console.log('The name of the changed field is', field.fieldName);
      console.log('The type of the changed field is', field.fieldType);
      console.log('The value of the changed field is', field.fieldValue);
      console.log('The hasAppearance of the changed field is', field.fieldHasAppearance);
    });
  }}
/>
```

#### annotationsListEditingEnabled
bool, optional, default value is true

If document editing is enabled, then this value determines if the annotation list is editable. 


```js
<DocumentView
  annotationsListEditingEnabled={true}
/>
```

#### disableEditingByAnnotationType
array of [`Config.Tools`](./src/Config/Config.ts) constants, optional, defaults to none.

Defines annotation types that cannot be edited after creation.

```js
<DocumentView
  disableEditingByAnnotationType={[Config.Tools.annotationCreateTextSquiggly, Config.Tools.annotationCreateEllipse]}
/>
```

#### highlighterSmoothingEnabled
bool, optional, default to true, Android only.

Sets whether the pdf should have highlighter smoothing.
Example

```js
<DocumentView
  highlighterSmoothingEnabled={false}
/>
```

#### excludedAnnotationListTypes
array of [`Config.Tools`](./src/Config/Config.ts) constants, optional, defaults to none

Defines types to be excluded from the annotation list.
Example use:

```js
<DocumentView
  excludedAnnotationListTypes={[Config.Tools.annotationCreateEllipse, Config.Tools.annotationCreateRectangle, Config.Tools.annotationCreateRedaction]}
/>
```

### Bookmark

#### onBookmarkChanged
function, optional

This function is called if a change has been made to user bookmarks.

Parameters:

Name | Type | Description
--- | --- | ---
bookmarkJson | string | the list of current bookmarks in JSON