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/vue'
import { ScrollPluginPackage, ScrollStrategy } from '@embedpdf/plugin-scroll/vue'
 
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 Scoped Slot

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 exposes layout data for each one through its default scoped slot. This gives you complete control over the content of each page placeholder.

<script setup lang="ts">
import { RenderLayer } from '@embedpdf/plugin-render/vue';
</script>
<template>
  <Scroller>
    <template #default="{ page }">
      <div :style="{ width: `${page.width}px`, height: `${page.height}px`, position: 'relative' }">
        <RenderLayer :page-index="page.pageIndex" :scale="page.scale" />
      </div>
    </template>
  </Scroller>
</template>

Page Navigation

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

<script setup lang="ts">
import { useScroll } from '@embedpdf/plugin-scroll/vue';
 
const { provides: scroll, state } = useScroll();
</script>
 
<template>
  <div v-if="scroll">
    <span>Page {{ state.currentPage }} of {{ state.totalPages }}</span>
    <button @click="scroll.scrollToNextPage()">Next</button>
  </div>
</template>

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.

Default Scoped Slot Props

Composable: useScroll()

A convenience composable for building page navigation UIs.

Returns

state Properties

provides Methods (ScrollCapability)