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/svelte'
 
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 stores 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.

<script lang="ts">
import { Viewport } from '@embedpdf/plugin-viewport/svelte';
import { Scroller } from '@embedpdf/plugin-scroll/svelte';
 
let { documentId }: { documentId: string } = $props();
</script>
 
<Viewport {documentId} class="h-full w-full bg-gray-100">
  <Scroller {documentId} {renderPage} />
</Viewport>

Programmatic Scrolling

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

<script lang="ts">
import { useViewportCapability } from '@embedpdf/plugin-viewport/svelte';
 
let { documentId }: { documentId: string } = $props();
 
const viewportCapability = useViewportCapability();
const viewport = $derived(viewportCapability.provides?.forDocument(documentId));
 
const scrollToTop = () => {
  viewport?.scrollTo({ x: 0, y: 0, behavior: 'smooth' });
};
</script>
 
<button onclick={scrollToTop}>Scroll to Top</button>

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 store. This store returns the reactive state for a specific document.

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

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.

Store: useViewportCapability()

Connects your component to the viewport’s functions.

Returns

ViewportCapability Methods

ViewportScope Methods (Returned by forDocument)

Store: useViewportScrollActivity(documentId)

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

Parameters

Returns (ScrollActivity)