DIAL PDF Highlighter

The DIAL PDF Highlighter (@epam/ai-dial-react-pdf-highlighter) is a set of React components for viewing PDF files with highlights, zoom, highlight navigation, and page thumbnails. DIAL Chat uses it to show PDF attachments. It wraps @epam/pdf-highlighter-kit and draws its controls with the UI Kit. This reference is for frontend developers who show PDF files in a React interface, for example to point at the passages an application cites.

Version scope

Everything below is checked against PDF Highlighter 0.3.0: its package.json, src/index.ts, src/components/DocumentPreview/DocumentPreview.tsx, and the README. DIAL Chat 1.2.22 ships 0.2.0; see Versions in DIAL releases. The repository's CHANGELOG.md stops at 0.1.3, so the GitHub release notes are the record of later changes.

Install

npm install @epam/ai-dial-react-pdf-highlighter@0.3.0 @epam/pdf-highlighter-kit@0.0.20 @epam/ai-dial-ui-kit@0.16.0 pdfjs-dist@5.4.149 react@19.2.5 react-dom@19.2.5

Peer dependency	Range	Required
`react`, `react-dom`	`>=19.2.5`	Yes
`@epam/ai-dial-ui-kit`	0.15.0 and later	Yes
`@epam/pdf-highlighter-kit`	`>=0.0.19`	Yes
`pdfjs-dist`	`^5.4.149`	Yes. The version must also satisfy the requirements of `@epam/pdf-highlighter-kit`.
`@tabler/icons-react`	`^3.44.0`	Only for `DocumentPreview`

The exact UI Kit range is >=0.15.0-0 || >=0.16.0-0. Release 0.3.0 is built and tested against UI Kit 0.16.0 and @epam/pdf-highlighter-kit 0.0.20.

Load the stylesheets in this order:

import '@epam/ai-dial-ui-kit/styles.css';
import '@epam/ai-dial-react-pdf-highlighter/styles.css';

Components and hooks

Export	What it is
`DocumentPreview`	A full preview: loading and error overlays, a toolbar with zoom and highlight navigation, and optional thumbnails
`PDFViewer`	The low-level viewer that wraps `@epam/pdf-highlighter-kit`, with props of type `PdfViewerProps`
`DocumentPreviewCacheProvider`	A context provider that shares loaded PDF files between previews, so the same file is not fetched twice
`PdfPreviewLoader`	The loading and error overlay that `DocumentPreview` uses
`PageThumbnail`	One PDF page rendered as a thumbnail
`useDocumentPreview`	The logic of `DocumentPreview`: file fetching with the cache, highlight navigation, zoom, and thumbnails, for a custom layout
`useDocumentPreviewCache`	The cache context, or `null` outside `DocumentPreviewCacheProvider`

The package also exports the zoom constants (ZOOM_OPTIONS, AUTO_ZOOM_ID, FIT_ZOOM_ID), the thumbnail constants, isPdfFile, getStepZoomOptionValue, the RotationDirection enum, and the PdfViewerApi, ZoomOption, ViewerOptions, and PageRotationDegrees types.

Example

import {
  DocumentPreview,
  DocumentPreviewCacheProvider,
} from '@epam/ai-dial-react-pdf-highlighter';
import '@epam/ai-dial-ui-kit/styles.css';
import '@epam/ai-dial-react-pdf-highlighter/styles.css';

export const Preview = () => (
  <DocumentPreviewCacheProvider>
    <DocumentPreview
      fileUrl="https://<YOUR_HOST>/document.pdf"
      loadFileCb={(url) => fetch(url).then((response) => response.blob())}
      highlights={[]}
    />
  </DocumentPreviewCacheProvider>
);

DocumentPreview props

Prop	Default	Description
`fileUrl`	—	Required. The URL passed to `loadFileCb` to fetch the PDF file.
`loadFileCb`	—	Required. Loads the file as a `Blob`. Under `DocumentPreviewCacheProvider`, it runs only on a cache miss.
`highlights`	—	Required. The highlights to draw, as `@epam/pdf-highlighter-kit` `InputHighlightData` objects.
`fileName`	`fileUrl`	The name used to detect a PDF file. Without it, the last segment of the `fileUrl` path is checked, and a segment with no extension counts as a PDF.
`title`	—	A title shown in the middle of the toolbar
`showOccurrences`	`true`	Shows the highlight counter in the toolbar
`selectedHighlightId`	—	The highlight to navigate to. When `showOccurrences` is `true`, the built-in counter takes precedence.
`selectedPageNumber`	—	Navigates to this page
`selectedPages`	—	Loads only these pages
`thumbnailPageNumbers`	—	The pages to render as thumbnails, in batches
`showLoaderOverlay`	—	Keeps the loading overlay visible while the parent does other work
`viewerOptions`	—	Options merged over the viewer defaults: `enableTextSelection: true`, `enableVirtualScrolling: true`, and `bboxOrigin: 'top-left'`
`errorLabel`, `occurrencesLabel`, `unsupportedLabel`	—	Labels for a load error, the highlight counter, and a file that is not a PDF
`containerClassName`, `pdfViewerClassName`	—	Classes for the outer wrapper and for the inner `PDFViewer`
`onViewerReady`	—	Called with the `PdfViewerApi` when the viewer is ready
`onCurrentPageChange`	—	Called with the 1-based number of the most visible page, including when the reader scrolls
`onTotalPagesChange`	—	Called when the page count is known
`onThumbnailsLoaded`	—	Called after each batch of thumbnails, with a `Map` from page number to thumbnail

Next.js

PDF rendering may work only on the client. If server-side rendering fails, load the viewer components with next/dynamic and ssr: false.

Version scope​

Install​

Components and hooks​

Example​

DocumentPreview props​

Next.js​

Further reading​