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 thensampleParameter 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 bboxThe 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