react-pdf-highlighter

The library uses two primary ways to represent where a highlight is located on a page:

1. ScaledPosition: Used for creating and storing highlights. It uses Scaled rectangles which are relative to the viewport/display size. It includes a usePdfCoordinates boolean to indicate if the coordinates should be treated as PDF-native.
2. Position: Used for viewport-based rendering. It uses LTWHP (Left, Top, Width, Height) rectangles and is tied to a specific pageNumber.

Both types contain a boundingRect (the overall area) and an array of rects (the individual lines or segments of the highlight).

export interface Scaled {
  x1: number;
  y1: number;
  x2: number;
  y2: number;
  width: number;
  height: number;
  pageNumber?: number;
}

export interface ScaledPosition {
  boundingRect: Scaled;
  rects: Array<Scaled>;
  pageNumber: number;
  usePdfCoordinates?: boolean;
}

export interface Position {
  boundingRect: LTWHP;
  rects: Array<LTWHP>;
  pageNumber: number;
}

The highlightTransform prop is a required function that determines how each highlight is rendered in the UI. It is called for every highlight in the highlights array.

Arguments:

• highlight: The current highlight object (of type T_ViewportHighlight<T_HT>).
• index: The index of the highlight in the array.
• setTip: A function to show a floating 'tip' (popover/menu) at the highlight's position.
  • Signature: (highlight: T_ViewportHighlight<T_HT>, callback: (highlight: T_ViewportHighlight<T_HT>) => JSX.Element) => void
• hideTip: A function to dismiss the current tip.
• viewportToScaled: A utility to convert coordinates from the PDF viewport to scaled coordinates.
• screenshot: A utility to capture an image of a specific area (LTWH) on a page.
• isScrolledTo: A boolean indicating if this specific highlight is currently the one being scrolled into view.

Return Value:

• A JSX.Element representing the visual highlight (e.g., a colored overlay or a marker).

The PdfLoader component is responsible for loading a PDF document using pdfjs-dist. It manages the lifecycle of the PDF document, including loading, error handling, and cleaning up resources when the component unmounts.

It uses a render prop pattern: you provide a children function that receives the loaded pdfDocument (of type PDFDocumentProxy), allowing you to render the PDF once it is ready.

Key Props:

• url (required): The URL of the PDF document to load.
• children: A function that receives the pdfDocument and returns a JSX.Element.
• beforeLoad: A JSX.Element to display while the PDF is loading.
• errorMessage: An optional JSX.Element to display if an error occurs. If provided, it can receive the error as a prop via React.cloneElement.
• workerSrc: The path to the PDF.js worker script. Defaults to a CDN version of pdfjs-dist@4.4.168.
• onError: A callback function invoked when an error occurs during loading.
• cMapUrl / cMapPacked: Configuration for character maps used in PDF rendering.

The PdfHighlighter component is the primary entry point for integrating PDF highlighting capabilities into a React application. It requires a pdfDocument (from pdfjs-dist) and a set of callback props to handle user interactions like text selection, area selection, and scrolling.

Key Props

• pdfDocument: The PDFDocumentProxy instance.
• highlights: An array of highlight objects (extending IHighlight).
• highlightTransform: A function used to render the UI for each highlight. It provides access to tools like viewportToScaled, screenshot, and setTip.
• onSelectionFinished: A callback triggered when a user finishes selecting text or an area. It provides the scaledPosition, content (text or image), and functions to hide the selection or transform it into a 'ghost' highlight.
• scrollRef: A callback that provides a scrollTo function, allowing you to programmatically navigate to specific highlights.
• onScrollChange: A callback triggered when the PDF viewer scrolls.
• pdfScaleValue: Controls the PDF zoom level (defaults to "auto").
• enableAreaSelection: An optional function to enable non-text (area) selection. It receives the MouseEvent and should return true if selection should proceed.
• pdfViewerOptions: Optional configuration passed directly to the underlying pdfjs-dist PDFViewer.

Example Usage

<PdfHighlighter
  pdfDocument={myPdfDocument}
  highlights={myHighlights}
  highlightTransform={(highlight, index, setTip, hideTip, viewportToScaled, screenshot, isScrolledTo) => (
    <div key={highlight.id} onClick={() => setTip(highlight.position, <MyTipComponent />)}>
      {/* Custom highlight UI */}
    </div>
  )}
  onSelectionFinished={(position, content, hideTipAndSelection, transformSelection) => {
    console.log('New selection:', position, content);
    return <MySelectionMenu onSave={...} />;
  }}
  scrollRef={(scrollTo) => {
    // Use scrollTo(highlight) to navigate
  }}
  onScrollChange={() => console.log('scrolled')}
/>