@duallab/verapdf-js-viewer

veraPDF-js-viewer

Display PDF with an option to highlight a collection of rectangles on top of page rendering. Used by veraPDF web application to visualize locations of validation errors

Compatibility

React

To use the latest version of veraPDF-js-viewer, your project needs to use React 16.3 or later.

Internet Explorer

Internet Explorer is not supported in veraPDF-js-viewer. Use Edge instead

Usage

Here's an example of basic usage:

import React, { useState } from 'react';
import PdfViewer from '@duallab/verapdf-js-viewer';

function MyApp() {
  const [numPages, setNumPages] = useState(null);
  const [pageNumber, setPageNumber] = useState(1);

  function onDocumentLoadSuccess({ numPages }) {
    setNumPages(numPages);
  }

  return (
    <div>
      <PdfViewer
        file="somefile.pdf"
        onLoadSuccess={onDocumentLoadSuccess}
      />
      <p>Page {pageNumber} of {numPages}</p>
    </div>
  );
}

Input parameters

Prop name	Description	Default value	Example values
Document props
className	Class name(s) that will be added to rendered element.	n/a	"custom-class-name-1 custom-class-name-2"
file	What PDF should be displayed. Its value can be an URL, a file (imported using import ... from ... or from file input form element), or an object with parameters (url - URL; data - data, preferably Uint8Array; range - PDFDataRangeTransport; httpHeaders - custom request headers, e.g. for authorization), withCredentials - a boolean to indicate whether or not to include cookies in the request (defaults to false). Warning: Since equality check (===) is used to determine if file object has changed, it must be memoized by setting it in component's state, useMemo or other similar technique.	n/a	URL: "http://example.com/sample.pdf" File: import sample from '../static/sample.pdf' and then sample Parameter object: { url: 'http://example.com/sample.pdf', httpHeaders: { 'X-CustomHeader': '40359820958024350238508234' }, withCredentials: true }
bboxes	Array of bboxes [ {location, groupId, bboxTitle, isVisible} ] that will be rendered as selectable rectangles over pdf pages. isVisible is an optional flag that specifies whether bbox should be shown on the canvas (default value: true). Bboxes can be grouped by optional parameter groupId. If error's check has 3rd item (2nd index) of errorArguments, it can be grouped with other checks with the same id from check.errorArguments[2] ('${clause}-${testNumber}-${check.errorArguments[2]}' => 4.1.2-9-79) bboxTitle is an optional parameter that is set to title and aria-describedby bounding box attributes. Currently support these locations: JSON string of bbox object: {"bbox":[{"p":1,"rect":[x,y,x2,y2]}]} String with coordinates for left-bottom point and top-right:pages[1-2]/boundingBox[x,y,x2,y2] String path through tagged structure tree: root/document[0]/pages[1](1 0 obj PDPage)/annots[1](100 0 obj PDLinkAnnot) String path to glyph in page stream: root/document[0]/pages[0](14 0 obj PDPage)/contentStream[0](20 0 obj PDSemanticContentStream)/operators[6]/usedGlyphs[5](OPCPIB+TimesNewRomanPSMT OPCPIB+TimesNewRomanPSMT 32 0 56991387 0) New contexts will be added.	n/a	[{ groupId: '4.1.2-9-79', location: 'pages[2-4]/boundingBox[10,200,300,400]' }]
activeBboxIndex	Index of active bbox from bboxes array	n/a	0
activeBboxId	Id of active tree bbox	n/a	"0:3:11:0"
showAllPages	Boolean flag to show pdf with all pages with scroll or single page	false	true
isTreeBboxesVisible	Boolean flag to show tree bboxes	false	true
error	What the component should display in case of an error.	"Failed to load PDF file."	String: "An error occurred!" React element: <div>An error occurred!</div> Function: this.renderError
treeBboxSelectionMode	String that determines how tree bboxes are highlighted: The value "SELECTED" selects only the current bbox The value "SELECTED_WITH_KIDS" selects the current bbox and all child bboxes	"SELECTED"	One of the following values: "SELECTED" "SELECTED_WITH_KIDS"
externalLinkTarget	Link target for external links rendered in annotations.	unset, which means that default behavior will be used	One of valid values for target attribute. "_self" "_blank" "_parent" "_top"
loading	What the component should display while loading.	"Loading PDF…"	String: "Please wait!" React element: <div>Please wait!</div> Function: this.renderLoader
noData	What the component should display in case of no data.	"No PDF file specified."	String: "Please select a file." React element: <div>Please select a file.</div> Function: this.renderNoData
rotate	Rotation of the document in degrees. If provided, will change rotation globally, even for the pages which were given rotate prop of their own. 90 = rotated to the right, 180 = upside down, 270 = rotated to the left.	n/a	90
onLoadSuccess	Function called when the document is successfully loaded.	n/a	(pdf) => alert('Loaded a file with ' + pdf.numPages + ' pages!')
onLoadError	Function called in case of an error while loading a document.	n/a	(error) => alert('Error while loading document! ' + error.message)
onItemClick	Function called when an outline item has been clicked. Usually, you would like to use this callback to move the user wherever they requested to.	n/a	({ pageNumber }) => alert('Clicked an item from page ' + pageNumber + '!')
onBboxClick	Function called when an bbox item has been clicked.	n/a	(bboxData) => alert('Selected bbox from ' + bboxData.page + ' page!')
onPageChange	Function called when page changed during scrolling	n/a	(page: number) => alert('New page ' + page);
onWarning	Function called in case of a warning for the selected bounding box. The warning is described by the code from the list: BBOX_OUT_OF_THE_PAGE_VIEWPORT (selected bounding box is out of the page viewport)	n/a	(warningCode: string) => alert('Warning: ' + warningCode);
Page props
page	Which page from PDF file should be displayed, by page number. In case showAllPages={true} autoscroll to provided page	1	2
inputRef	A prop that behaves like ref, but it's passed to main <div> rendered by <Page> component.	n/a	Function: (ref) => { this.myPage = ref; } Ref created using React.createRef: this.ref = React.createRef(); … inputRef={this.ref} Ref created using React.useRef: const ref = React.useRef(); … inputRef={ref}
pageError	What the component should display in case of an error.	"Failed to load the page."	String: "An error occurred!" React element: <div>An error occurred!</div> Function: this.renderError
height	Page height. If neither height nor width are defined, page will be rendered at the size defined in PDF. If you define width and height at the same time, height will be ignored. If you define height and scale at the same time, the height will be multiplied by a given factor.	Page's default height	300
width	Page width. If neither height nor width are defined, page will be rendered at the size defined in PDF. If you define width and height at the same time, height will be ignored. If you define width and scale at the same time, the width will be multiplied by a given factor.	Page's default width	300
pageLoading	What the component should display while loading.	"Loading page…"	String: "Please wait!" React element: <div>Please wait!</div> Function: this.renderLoader
renderAnnotationLayer	Whether annotations (e.g. links) should be rendered.	true	false
renderInteractiveForms	Whether interactive forms should be rendered. renderAnnotationLayer prop must be set to true.	false	true
renderTextLayer	Whether a text layer should be rendered.	true	false
scale	Page scale.	1.0	0.5
onPageLoadError	Function called in case of an error while loading the page.	n/a	(error) => alert('Error while loading page! ' + error.message)
onPageLoadProgress	Function called, potentially multiple times, as the loading progresses.	n/a	({ loaded, total }) => alert('Loading a document: ' + (loaded / total) * 100 + '%');
onPageLoadSuccess	Function called when the page is successfully loaded.	n/a	(page) => alert('Now displaying a page number ' + page.pageNumber + '!')
onPageRenderError	Function called in case of an error while rendering the page.	n/a	(error) => alert('Error while loading page! ' + error.message)
onPageRenderSuccess	Function called when the page is successfully rendered on the screen.	n/a	() => alert('Rendered the page!')
onBboxesParsed	Function called after bboxes were parsed and returns array of pages.	n/a	(pages) => console.log(pages)
onGetAnnotationsSuccess	Function called when annotations are successfully loaded.	n/a	(annotations) => alert('Now displaying ' + annotations.length + ' annotations!')
onGetAnnotationsError	Function called in case of an error while loading annotations.	n/a	(error) => alert('Error while loading annotations! ' + error.message)
onGetTextSuccess	Function called when text layer items are successfully loaded.	n/a	({ items }) => alert('Now displaying ' + items.length + ' text layer items!')
onGetTextError	Function called in case of an error while loading text layer items.	n/a	(error) => alert('Error while loading text layer items! ' + error.message)
onSelectBbox	Function that is called when the bbox is selected by keypress handlers.	n/a	(index) => alert('Select bounding box with index: ' + index)
customTextRenderer	Function that customizes how a text layer is rendered.	n/a	({ str, itemIndex }) => str.replace(/ipsum/g, value => ${value})
Bbox props
colorScheme	Set custom colors for bbox	{ border?: string; borderSelected?: string; borderRelated?: string; borderStructured?: string; borderStructuredSelected?: string; borderHovered?: string; borderStructuredHovered?: string; background?: string; backgroundSelected?: string; backgroundHovered?: string; backgroundRelated?: string; backgroundStructured?: string; backgroundStructuredSelected?: string;}	n/a
renderBbox	Function for rendering custom Bbox component	n/a	({ left: string; width: string; height: string; top: string; disabled: boolean; related?: boolean; selected?: boolean; structured?: boolean; scale: number; colorScheme?: IColorScheme; selectionMode?: TreeBboxSelectionMode; onClick?(e: any): void; }) => ReactElement

Shortcuts

Bounding box selection (see onSelectBbox prop):

• Ctrl/⌘ + Up Arrow - select next bounding box
• Ctrl/⌘ + Down Arrow - select previous bounding box

Page scrolling:

• Up Arrow - scroll up
• Down Arrow - scroll down
• Right Arrow - scroll to next page
• Left Arrow - scroll to previous page

Useful links

• React-PDF