Viewport Plugin

The Viewport Plugin is a foundational element for any viewer. It provides the <Viewport /> component, which acts as the scrollable “window” through which users see the PDF pages.

This plugin is designed for multi-document layouts. It manages metrics, scroll state, and dimensions independently for every open document, allowing you to build split-screen views, tabbed interfaces, or multi-window applications easily.

Installation

The plugin is available as a separate NPM package.

npm install @embedpdf/plugin-viewport

pnpm add @embedpdf/plugin-viewport

yarn add @embedpdf/plugin-viewport

bun add @embedpdf/plugin-viewport

Registration

Import ViewportPluginPackage and add it to the plugins array.

import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/react'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(DocumentManagerPluginPackage, { /* ... */ }),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),
 
  // Register and configure the viewport plugin
  createPluginRegistration(ViewportPluginPackage, {
    viewportGap: 20, // Adds 20px of padding inside the viewport
  }),
]

Usage

The plugin provides the <Viewport /> component for the UI and hooks for programmatic control.

The <Viewport /> Component

The <Viewport /> component is the main scrollable container. You must provide a documentId to link the scroll container to the specific document state managed by the engine.

<Viewport
  documentId={activeDocumentId} // Required: The ID of the document being displayed
  className="h-full w-full bg-gray-100"
>
  <Scroller
    documentId={activeDocumentId} // Scroller also requires the ID
    renderPage={...}
  />
</Viewport>

Programmatic Scrolling

To scroll a specific document programmatically, use useViewportCapability to get the API, then use .forDocument(id) to target the specific viewport.

import { useViewportCapability } from '@embedpdf/plugin-viewport/react';
 
const ScrollToTopButton = ({ documentId }) => {
  const { provides: viewportPlugin } = useViewportCapability();
 
  // Get the API scoped to this specific document
  const viewport = viewportPlugin?.forDocument(documentId);
 
  const handleClick = () => {
    viewport?.scrollTo({ x: 0, y: 0, behavior: 'smooth' });
  };
 
  return <button onClick={handleClick}>Top</button>;
};

Monitoring Scroll Activity

To react to scrolling events (e.g., to show a “Back to Top” button or hide a floating toolbar), use the useViewportScrollActivity hook. This hook returns the reactive state for a specific document.

import { useViewportScrollActivity } from '@embedpdf/plugin-viewport/react';
 
const ScrollIndicator = ({ documentId }) => {
  // Pass the documentId to track
  const activity = useViewportScrollActivity(documentId);
 
  if (activity.isScrolling) {
    return <span>Scrolling...</span>;
  }
  return <span>Idle</span>;
};

Live Example

This example demonstrates a complete setup. It loads a document, passes the documentId to the components, and creates a toolbar that controls scrolling for that specific document.

API Reference

Configuration (ViewportPluginConfig)

Component: <Viewport />

A div-based component that acts as the scrollable container. It accepts all standard div props like style and className.

Hook: useViewportCapability()

Connects your component to the viewport’s functions.

Returns

ViewportCapability Methods

ViewportScope Methods (Returned by forDocument)

Hook: useViewportScrollActivity(documentId)

A hook for tracking the scroll state of a specific document.

Returns (ScrollActivity)