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 composable 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'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/vue'
import { ScrollPluginPackage, ScrollStrategy } from '@embedpdf/plugin-scroll/vue'
 
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 scoped slot is called for each visible page, receiving layout information, allowing you to render the page content (e.g., using <RenderLayer />).

<template>
  <Viewport :document-id="activeDocumentId">
    <Scroller :document-id="activeDocumentId">
      <template #default="{ page }">
        <div :style="{ width: `${page.width}px`, height: `${page.height}px`, position: 'relative' }">
          <RenderLayer :document-id="activeDocumentId" :page-index="page.pageIndex" />
        </div>
      </template>
    </Scroller>
  </Viewport>
</template>

Page Navigation

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

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

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 capability. 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.

Default Scoped Slot Props

Composable: useScroll(documentId)

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

Parameters

Returns

provides Methods (ScrollScope)

Events (ScrollCapability)

Access events via useScrollCapability().