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 composable 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'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/svelte'
import { ScrollPluginPackage, ScrollStrategy } from '@embedpdf/plugin-scroll/svelte'
 
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 composable for navigation.

The <Scroller /> and Snippets

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 uses your provided snippet to render each one. This gives you complete control over the content of each page placeholder.

<script lang="ts">
import { RenderLayer } from '@embedpdf/plugin-render/svelte';
import { Scroller, type RenderPageProps } from '@embedpdf/plugin-scroll/svelte';
import { Viewport } from '@embedpdf/plugin-viewport/svelte';
</script>
 
{#snippet RenderPageSnippet(page: RenderPageProps)}
  <div style:width={`${page.width}px`} style:height={`${page.height}px`} style:position="relative">
    <RenderLayer pageIndex={page.pageIndex} scale={page.scale} />
  </div>
{/snippet}
 
<Viewport>
  <Scroller {RenderPageSnippet} />
</Viewport>

Page Navigation

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

<script lang="ts">
import { useScroll } from '@embedpdf/plugin-scroll/svelte';
 
const scroll = useScroll();
</script>
 
{#if scroll.provides}
  <div>
    <span>Page {scroll.state.currentPage} of {scroll.state.totalPages}</span>
    <button onclick={() => scroll.provides?.scrollToNextPage()}>Next</button>
  </div>
{/if}

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.

Composable: useScroll()

A convenience composable for building page navigation UIs.

Returns

An object with the following properties:

state Properties

provides Methods (ScrollCapability)