Thumbnail Plugin

The Thumbnail Plugin adds a classic sidebar view with small, clickable previews of each page. It helps users orient themselves within a document and navigate quickly.

To ensure optimal performance with large documents, the plugin implements virtualization. It only renders the thumbnail images currently visible in the sidebar, recycling DOM elements as the user scrolls.

This plugin supports multi-document layouts, maintaining independent thumbnail lists, scroll positions, and render queues for every open document.

Installation

This plugin depends on the Render plugin to generate the images.

npm install @embedpdf/plugin-thumbnail @embedpdf/plugin-render

pnpm add @embedpdf/plugin-thumbnail @embedpdf/plugin-render

yarn add @embedpdf/plugin-thumbnail @embedpdf/plugin-render

bun add @embedpdf/plugin-thumbnail @embedpdf/plugin-render

Registration

Import ThumbnailPluginPackage and its dependencies.

import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import { RenderPluginPackage } from '@embedpdf/plugin-render/svelte'
import { ThumbnailPluginPackage } from '@embedpdf/plugin-thumbnail/svelte'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(DocumentManagerPluginPackage, { /* ... */ }),
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(RenderPluginPackage), // Required dependency
 
  // Register and configure the thumbnail plugin
  createPluginRegistration(ThumbnailPluginPackage, {
    width: 120, // Sets the width of thumbnail images
  }),
]

Usage

The plugin provides two main components: <ThumbnailsPane /> (the virtualized container) and <ThumbImg /> (the actual image renderer).

Building a Sidebar

You typically place <ThumbnailsPane /> in a sidebar container. It uses a snippet pattern: you provide a template that receives metadata (meta) for each visible item, and you return the markup for that thumbnail.

You must provide the documentId to both components to link them to the correct document state.

The meta Object

The meta object passed to your snippet contains calculated layout values. You must apply these styles for virtualization to work:

• meta.top: Absolute vertical position. Apply to top.
• meta.wrapperHeight: Total height of the item row. Apply to height.
• meta.width / meta.height: Dimensions of the image itself.

<script lang="ts">
import { useScroll } from '@embedpdf/plugin-scroll/svelte';
import { ThumbnailsPane, ThumbImg, type ThumbMeta } from '@embedpdf/plugin-thumbnail/svelte';
 
let { documentId }: { documentId: string } = $props();
const scroll = useScroll(() => documentId);
</script>
 
<div class="relative h-full overflow-hidden">
  <ThumbnailsPane {documentId}>
    {#snippet children(meta: ThumbMeta)}
      <button
        type="button"
        class="absolute flex w-full cursor-pointer flex-col items-center"
        style:height="{meta.wrapperHeight}px"
        style:top="{meta.top}px"
        onclick={() => scroll.provides?.scrollToPage?.({ pageNumber: meta.pageIndex + 1 })}
      >
        <div
          class={scroll.state.currentPage === meta.pageIndex + 1 ? 'ring-2 ring-blue-500' : ''}
          style:width="{meta.width}px"
          style:height="{meta.height}px"
        >
          <ThumbImg {documentId} {meta} />
        </div>
        <span>{meta.pageIndex + 1}</span>
      </button>
    {/snippet}
  </ThumbnailsPane>
</div>

Live Example

This example shows a complete PDF viewer with a thumbnail sidebar. Notice how the sidebar automatically scrolls to track the current page in the main viewport.

API Reference

Configuration (ThumbnailPluginConfig)

Component: <ThumbnailsPane />

The virtualized scroll container.

Snippet: children(meta: ThumbMeta)

A snippet that defines how to render each thumbnail. The meta object contains:

Component: <ThumbImg />

Renders the rasterized image for a thumbnail.

Store: useThumbnailCapability()

Access the plugin API.

ThumbnailCapability Methods

ThumbnailScope Methods (Returned by forDocument)