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.

This plugin is designed for multi-document layouts. It manages metrics, scroll state, and dimensions independently for every open document, allowing you to build split-screen views, tabbed interfaces, or multi-window applications easily.

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.

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

Usage

The plugin provides the <Viewport /> component for the UI and composables for programmatic control.

The <Viewport /> Component

The <Viewport /> component is the main scrollable container. You must provide a documentId to link the scroll container to the specific document state managed by the engine.

<template>
  <Viewport
    :document-id="activeDocumentId"
    class="h-full w-full bg-gray-100"
  >
    <Scroller :document-id="activeDocumentId">
      <!-- page content -->
    </Scroller>
  </Viewport>
</template>

Programmatic Scrolling

To scroll a specific document programmatically, use useViewportCapability to get the API, then use .forDocument(id) to target the specific viewport.

<script setup lang="ts">
import { computed } from 'vue';
import { useViewportCapability } from '@embedpdf/plugin-viewport/vue';
 
const props = defineProps<{ documentId: string }>();
 
const { provides: viewportCapability } = useViewportCapability();
 
// Get the API scoped to this specific document
const viewport = computed(() => viewportCapability.value?.forDocument(props.documentId));
 
const scrollToTop = () => {
  viewport.value?.scrollTo({ x: 0, y: 0, behavior: 'smooth' });
};
</script>
 
<template>
  <button @click="scrollToTop">Top</button>
</template>

Monitoring Scroll Activity

To react to scrolling events (e.g., to show a “Back to Top” button or hide a floating toolbar), use the useViewportScrollActivity composable. This composable returns the reactive state for a specific document.

<script setup lang="ts">
import { useViewportScrollActivity } from '@embedpdf/plugin-viewport/vue';
 
const props = defineProps<{ documentId: string }>();
 
// Pass a getter that returns the documentId to track
const scrollActivity = useViewportScrollActivity(() => props.documentId);
</script>
 
<template>
  <span v-if="scrollActivity.isScrolling">Scrolling...</span>
  <span v-else>Idle</span>
</template>

Live Example

This example demonstrates a complete setup. It loads a document, passes the documentId to the components, and creates a toolbar that controls scrolling for that specific document.

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

ViewportScope Methods (Returned by forDocument)

Composable: useViewportScrollActivity(documentId)

A composable for tracking the scroll state of a specific document.

Parameters

Returns (ScrollActivity)