API reference

Import public APIs from @anaralabs/lector. This reference follows packages/lector/src/index.ts and the implementation on main; compare your installed version with the releases if a symbol is missing. Do not import from src/internal or a package-internal path.

Root

Loads one document and supplies its context. Accepts HTML div props in addition to the document options below. Its onError is a Lector callback, not a DOM error handler.

source changes trigger loading. Keep object and binary sources stable. The zoom props initialize state; use store actions for subsequent changes. Changing documentOptions, progressive, or initialPage alone does not reload the document. See loading documents for source handling, retries, and asset paths.

The current type also contains initialRotation, but Root does not forward it into document initialization. Do not rely on it for rotation controls.

Pages and Page

Both accept HTML div props. Pages supplies its own scrolling and a default height of 100%; its parent needs a definite height. Page establishes page-number context and owns viewport dimensions. See layout.

Page layers

All page layers belong under Page.

CanvasLayer does not provide searchable DOM text. HighlightLayer needs a visible color or border from your styles. Links and fields need the PDF.js stylesheet.

Controls and thumbnails

Mount document controls under Root.

Outline, OutlineItem, and OutlineChildItems compose a document outline. Their current destination handling has page-index limitations, so verify navigation against your PDFs before using them. For a custom outline, the PDF.js document proxy exposes getOutline() and getDestination(). Convert PDF.js's zero-based getPageIndex() result to a one-based page number before calling jumpToPage.

usePdf

usePdf(selector) subscribes to the store belonging to the nearest Root. Select only the values your component needs. The provider is unavailable in Root's loader and outside its children.

"use client";
 
import { usePdf } from "@anaralabs/lector";
 
export default function FitWidthButton() {
  const fitWidth = usePdf((state) => state.zoomFitWidth);
  return <button type="button" onClick={fitWidth}>Fit width</button>;
}

These are the store fields most useful to application code:

The store also exposes rendering and virtualizer internals. Prefer the components and hooks above over mutating those fields.

usePdfJump

Requires Root and a mounted Pages virtualizer.

For rectangle navigation, align is "start" or "center" (default "start"), additionalOffset defaults to 0, and scroll behavior defaults to "smooth". Use the coordinate contract when supplying your own rectangles.

Search and selection

Use getDimension() with an undefined check. The getSelection() alias has a stronger return type than its runtime guarantee, so it does not remove that need. See search for options, result allocation, and indexing cost, and selection for a complete action.

Annotation and link integrations

The package also exports AnnotationsStoreProvider, useAnnotations, AnnotationTooltip, and the Annotation and AnnotationTooltipContentProps types for application-owned annotations. These use a separate annotation store; Root does not install that provider for you. Wrap each independent annotation session in AnnotationsStoreProvider; without it, useAnnotations uses a shared fallback store. The docs site's annotation demo source shows their composition.

LinkService, PDFLinkServiceContext, useCreatePDFLinkService, and usePDFLinkService expose the PDF link integration. Root installs the service; AnnotationLayer connects destination changes to scrolling. Use PDF links for the normal integration.

Public types and color utilities

HighlightRect, ColoredHighlight, SearchResult, and SearchResults describe overlay and search data. ColorScheme, DarkModeColors, and RenderColorMap describe color configuration. DEFAULT_DARK_MODE_COLORS and createDarkModeColorMap let your overlays use the same palette as the page. See dark mode.

Component props are inferred from the components rather than all being exported as named interfaces. For a wrapper, derive them with React.ComponentProps<typeof Root> (or the component you wrap).