Viewport Plugin

The Viewport Plugin is a foundational element for any viewer. It provides the <Viewport /> component, which acts as the scrollable “window” through which users see the PDF pages. It is responsible for tracking its own dimensions and scroll position and communicating that information to other plugins.

Installation

The plugin is available as a separate NPM package.

npm install @embedpdf/plugin-viewport

pnpm add @embedpdf/plugin-viewport

yarn add @embedpdf/plugin-viewport

bun add @embedpdf/plugin-viewport

Registration

Import ViewportPluginPackage and add it to the plugins array. It is highly recommended to include this plugin in any viewer build.

import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/vue'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),
 
  // Register and configure the viewport plugin
  createPluginRegistration(ViewportPluginPackage, {
    viewportGap: 10, // Adds 10px of padding inside the viewport
  }),
]

Usage

The plugin provides the <Viewport /> component, which you use to wrap your <Scroller />, and composables to interact with it programmatically.

The <Viewport /> Component

The <Viewport /> component is the main scrollable container for your PDF. You should place it in your layout and ensure it has a defined size (e.g., height: '500px' or a flex class). It automatically handles listening for scroll and resize events.

<template>
  <div style="height: 500px; display: flex;">
    <Viewport style="flex-grow: 1;">
      <Scroller>
      </Scroller>
    </Viewport>
  </div>
</template>

Programmatic Scrolling

You can control the viewport’s scroll position from any other component using the useViewportCapability composable. This is useful for features like a “scroll to top” button or navigating from a table of contents.

<script setup lang="ts">
import { useViewportCapability } from '@embedpdf/plugin-viewport/vue';
 
const { provides: viewport } = useViewportCapability();
 
const scrollToTop = () => {
  viewport.value?.scrollTo({ x: 0, y: 0, behavior: 'smooth' });
};
</script>
 
<template>
  <button @click="scrollToTop">Scroll to Top</button>
</template>

Monitoring Scroll Activity

The plugin also provides a useViewportScrollActivity composable that returns the current scrolling state. This is useful for creating UIs that react to user scrolling, such as auto-hiding toolbars.

Live Example

This example demonstrates a viewer with a toolbar that can programmatically scroll the viewport. It also includes an indicator that shows when the viewport is actively scrolling.

API Reference

Configuration (ViewportPluginConfig)

Component: <Viewport />

A div-based component that acts as the scrollable container. It accepts all standard div attributes like style and class.

Composable: useViewportCapability()

Connects your component to the viewport’s functions.

Returns

ViewportCapability Methods

Composable: useViewportScrollActivity()

A composable for tracking the scroll state of the viewport.

Returns

A reactive object with the following properties: