PdfProviders

The root provider of the SDK. It hosts the document and viewport state and accepts the configuration, so every SDK hook and component must be rendered inside it.

All props are optional; together they form the Config type. The PDF application re-renders whenever a prop changes identity, so keep the props referentially stable: define static configuration outside the component and memoize the rest (see Getting started).

The interaction tool and the content policy are described in useInteractionTool and CONTENT_POLICY_PRESET; change them later with useSetInteractionMode.

Theme

Theme fields, all optional:

StyleKeys names the styleable elements: scrollViewport, pagesContainer, page, pageCanvas, rubberbandSelection, resizable, resizableHandle, widgetOverlay, widgetPreview, widgetInput, widgetSignature, widgetSignatureHint, imagePreview, and searchMatch. The Theming and customization guide describes each element and the CSS variables.

searchMatch is the highlighted text of a search match. It is part of the text layout, so its styles must use paint properties only, such as background or color, and lengths with units ('4px', not 4): a padding, margin, or border would move the text. A classNames class can style the active match apart with a [data-active] selector.

Components

theme.components fields, all optional:

• A replacement can render the exported built-in component for the cases it doesn't customize.
• A string is taken as an HTML element name, such as 'div', not as text.
• PageOverlayProps are pageId, pageIndex (zero-based), and className. Add className to the overlay's root element: it positions the overlay over the page. The overlay sits above the page content, so give the parts that shouldn't intercept clicks pointer-events: none.

Zoom gestures

zoomGestures fields, all optional:

The bounds don't limit useViewportScale, which sets any positive scale.

Drag gestures

dragGestures is keyed by PointerType (mouse, pen, touch), and each entry is a PointerConfiguration deciding when a press on a draggable element turns into a drag, in one of two shapes:

• { promoteDelay, requireActive? } (TimerPointerConfiguration): the drag starts when the pointer is held still for promoteDelay milliseconds; moving it earlier cancels the drag. Suits low-precision input, such as touch.
• { suppressTime, suppressDistance, requireActive? } (SuppressPointerConfiguration): pointer movement within suppressDistance pixels during the first suppressTime milliseconds is ignored, so a shaky click isn't taken for a drag. Suits high-precision input, such as a mouse.

requireActive limits dragging to elements that are already selected, which keeps unselected blocks from interfering with scrolling on touch devices. By default, mouse and pen use { suppressTime: 150, suppressDistance: 10 }, and touch uses { promoteDelay: 300 }; a pointer type left out keeps its default.

Example

import { useMemo } from 'react'
import { CONTENT_POLICY_PRESET, PageOverlayProps, PdfProviders } from '@sdk-pdf/react'

function PageNumberOverlay({ pageIndex, className }: PageOverlayProps) {
  return (
    <div className={className} style={{ pointerEvents: 'none' }}>
      <span className="page-number">{pageIndex + 1}</span>
    </div>
  )
}

export function App({ viewportPadding }: { viewportPadding: number }) {
  const config = useMemo(
    () => ({
      theme: { viewportPadding, components: { pageOverlay: PageNumberOverlay } },
      initialContentPolicy: CONTENT_POLICY_PRESET.PDF_VIEWER,
    }),
    [viewportPadding]
  )

  return (
    <PdfProviders {...config}>
      <DocumentLoader />
    </PdfProviders>
  )
}