Scroll Plugin

The Scroll Plugin handles page layout, virtualization, and navigation logic. It provides the <Scroller /> component, which efficiently renders only the visible pages dynamically based on the current viewport position, and the useScroll hook for programmatic navigation.

This plugin works in tandem with the Viewport Plugin and supports multi-document layouts, managing independent scroll states and strategies (vertical/horizontal) for each open document.

Installation

This plugin depends on the Viewport plugin.

npm install @embedpdf/plugin-scroll @embedpdf/plugin-viewport

pnpm add @embedpdf/plugin-scroll @embedpdf/plugin-viewport

yarn add @embedpdf/plugin-scroll @embedpdf/plugin-viewport

bun add @embedpdf/plugin-scroll @embedpdf/plugin-viewport

Registration

Import ScrollPluginPackage and add it to your plugin configuration.

import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/react'
import { ScrollPluginPackage, ScrollStrategy } from '@embedpdf/plugin-scroll/react'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(DocumentManagerPluginPackage, { /* ... */ }),
  createPluginRegistration(RenderPluginPackage),
 
  // Register dependencies first
  createPluginRegistration(ViewportPluginPackage),
 
  // Register and configure the scroll plugin
  createPluginRegistration(ScrollPluginPackage, {
    defaultStrategy: ScrollStrategy.Vertical, // or Horizontal
    defaultPageGap: 10,
  }),
]

Usage

The <Scroller /> Component

The <Scroller /> component is the heart of the layout system. It must be placed inside a <Viewport />.

You must provide the documentId to link the scroller to the correct document state. The renderPage prop is a callback that receives layout information for a specific page, allowing you to render the page content (e.g., using <RenderLayer />).

<Viewport documentId={activeDocumentId}>
  <Scroller
    documentId={activeDocumentId} // Required
    renderPage={({ pageIndex, width, height, scale }) => (
      // This function is called for each visible page
      <div style={{ width, height, position: 'relative' }}>
        <RenderLayer documentId={activeDocumentId} pageIndex={pageIndex} scale={scale} />
      </div>
    )}
  />
</Viewport>

Page Navigation

To build navigation controls (like “Next Page” or “Go to Page 5”), use the useScroll hook. This hook requires the documentId of the target document.

import { useScroll } from '@embedpdf/plugin-scroll/react';
 
const PageControls = ({ documentId }) => {
  const { provides: scroll, state } = useScroll(documentId);
 
  return (
    <div>
      <span>Page {state.currentPage} of {state.totalPages}</span>
      <button onClick={() => scroll?.scrollToNextPage()}>Next</button>
    </div>
  );
};

Live Examples

Page Navigation

This example features a complete page navigation component that allows jumping to a specific page and moving forward or backward.

Scroll to Page on Load

To scroll to a specific page when a document loads, use the onLayoutReady event from the scroll plugin. This event fires once the document layout is fully initialized and ready for navigation.

API Reference

Configuration (ScrollPluginConfig)

Component: <Scroller />

The virtualized container that lays out pages.

Hook: useScroll(documentId)

Returns the scroll state and capability methods for a specific document.

Returns

provides Methods (ScrollScope)

Events (ScrollCapability)

Access events via useScrollCapability().