@epam/ai-dial-react-pdf-highlighter

AI DIAL React PDF Highlighter is a React component library for PDF viewing and highlights. It builds on top of @epam/pdf-highlighter-kit and uses @epam/ai-dial-ui-kit styles and components.

Part of the AI DIAL ecosystem.

Table of Contents

• Highlights
• Documentation
• Quick Start
  • Prerequisites
  • Installation
  • Peer Dependencies
  • Basic Usage
• Exported API
• Styles
• Development
  • Setup
  • Quality Checks
• Storybook
• Usage in Projects
  • Next.js
• Contributing
• Security
• License

Highlights

• React components for PDF viewing, thumbnailing, and highlights
• Higher-level API over pdf-highlighter-kit
• Built with TypeScript and strict typing
• Storybook + Vitest test setup
• Ready to publish and consume as an npm package

Documentation

You can explore components in Storybook during local development.

npm run storybook

Quick Start

Prerequisites

• Node.js >= 22.2.0
• npm >= 10.7.0

Installation

npm install @epam/ai-dial-react-pdf-highlighter

Peer Dependencies

| Type | Packages | npm | Yarn | | ---- | -------- | --- | ---- | | Required | react, react-dom, @epam/pdf-highlighter-kit, @epam/ai-dial-ui-kit, pdfjs-dist | npm install react react-dom @epam/pdf-highlighter-kit @epam/ai-dial-ui-kit pdfjs-dist | yarn add react react-dom @epam/pdf-highlighter-kit @epam/ai-dial-ui-kit pdfjs-dist | | Optional (for DocumentPreview) | @tabler/icons-react | npm install @tabler/icons-react | yarn add @tabler/icons-react |

Your pdfjs-dist version should satisfy pdf-highlighter-kit requirements.

Basic Usage

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';

function App() {
  return (
    <DocumentPreviewCacheProvider>
      <DocumentPreview
        fileUrl="https://example.com/document.pdf"
        loadFileCb={(url) => fetch(url).then((response) => response.blob())}
        highlights={[]}
      />
    </DocumentPreviewCacheProvider>
  );
}

Exported API

Components

| Name | Description | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | PDFViewer | Low-level PDF viewer component wrapping @epam/pdf-highlighter-kit. Accepts PdfViewerProps. | | DocumentPreview | High-level document preview with built-in loading, zoom, highlight navigation, and thumbnail support. Accepts DocumentPreviewProps. | | DocumentPreviewCacheProvider | Context provider that enables cross-component sharing of loaded PDF blobs. Wrap your app (or subtree) with this to avoid re-fetching the same files. | | PdfPreviewLoader | Standalone loading/error state overlay used internally by DocumentPreview. Accepts PdfPreviewLoaderProps. | | PageThumbnail | Renders a single PDF page as a thumbnail image. Accepts PageThumbnailProps. |

Hooks

useDocumentPreview(options: UseDocumentPreviewOptions): UseDocumentPreviewResult

Encapsulates all logic for a document preview: file fetching (with optional cache integration), highlight-index navigation, zoom state, and thumbnail generation. Use it to build a fully custom preview UI without taking on DocumentPreview's default layout.

useDocumentPreviewCache(): DocumentPreviewCacheContext | null

Returns the document preview cache context provided by DocumentPreviewCacheProvider. Returns null when called outside the provider. Consumed internally by useDocumentPreview to avoid re-fetching files already in the cache.

Styles

Import both stylesheets in your app entry point:

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

Development

Setup

git clone https://github.com/epam/ai-dial-react-pdf-highlighter.git
cd ai-dial-react-pdf-highlighter
npm install

Useful commands:

npm run dev
npm run storybook
npm run test:run
npm run test

Quality Checks

Before opening a PR, run:

npm run typecheck
npm run lint:check
npm run test:run

Or run the combined check:

npm run verify:agent-hook

Storybook

Development mode:

npm run storybook

Production build:

npm run build-storybook

Usage in Projects

Next.js

In some cases, PDF-related UI works only with dynamic imports on the client side. If you hit SSR issues, load viewer components with next/dynamic and ssr: false.

Contributing

Please read the contributing guide.

Security

If you find a vulnerability, please read our security policy.

License

Apache 2.0 © EPAM Systems