Scroll Plugin

The Scroll Plugin is a foundational plugin responsible for page layout, virtualization, and navigation. It provides the essential <Scroller /> component, which intelligently renders only the visible pages to ensure high performance, and the useScroll hook for building page navigation controls.

Installation

This plugin depends on the Viewport plugin. You must install both packages.

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 its Viewport dependency, and add them to the plugins array.

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(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(RenderPluginPackage),
 
  // Register dependencies first
  createPluginRegistration(ViewportPluginPackage),
 
  // Register and configure the scroll plugin
  createPluginRegistration(ScrollPluginPackage, {
    strategy: ScrollStrategy.Vertical, // or Horizontal
    initialPage: 1,
  }),
]

Usage

The plugin provides the <Scroller /> component for rendering pages and the useScroll hook for navigation.

The <Scroller /> and renderPage Prop

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

Crucially, the <Scroller /> does not render pages itself. Instead, it calculates which pages should be visible and calls the function you provide to its renderPage prop for each one. This gives you complete control over the content of each page placeholder.

import { RenderLayer } from '@embedpdf/plugin-render/react';
 
// ...
<Scroller
  renderPage={({ pageIndex, width, height, scale }) => (
    // This function is called for each visible page
    <div style={{ width, height, position: 'relative' }}>
      <RenderLayer pageIndex={pageIndex} scale={scale} />
    </div>
  )}
/>

Page Navigation

The useScroll hook provides everything you need to build a page navigation UI. It returns a provides object with action methods and a state object with reactive data like the current page number.

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

Live Example

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

API Reference

Configuration (ScrollPluginConfig)

Component: <Scroller />

The virtualized container that lays out pages.

Hook: useScroll()

A convenience hook for building page navigation UIs. It returns an object containing a provides object for actions and a state object for reactive data.

Returns

state Properties

provides Methods (ScrollCapability)