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'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import { RenderPluginPackage } from '@embedpdf/plugin-render/react'
import { ThumbnailPluginPackage } from '@embedpdf/plugin-thumbnail/react'
 
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 render prop pattern: you provide a function that receives metadata (m) for each visible item, and you return the JSX 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 render function contains calculated layout values. You must apply these styles for virtualization to work:

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

import { useScroll } from '@embedpdf/plugin-scroll/react';
import { ThumbnailsPane, ThumbImg } from '@embedpdf/plugin-thumbnail/react';
 
const ThumbnailSidebar = ({ documentId }) => {
  const { provides: scroll } = useScroll(documentId);
 
  return (
    <div className="relative h-full overflow-hidden">
      <ThumbnailsPane documentId={documentId}>
        {(m) => (
          <div
            key={m.pageIndex}
            style={{
              position: 'absolute',
              top: m.top,
              height: m.wrapperHeight,
              width: '100%'
            }}
            onClick={() => scroll?.scrollToPage({ pageNumber: m.pageIndex + 1 })}
          >
            {/* The actual image component */}
            <div style={{ width: m.width, height: m.height }}>
              <ThumbImg documentId={documentId} meta={m} />
            </div>
            <span>{m.pageIndex + 1}</span>
          </div>
        )}
      </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.

Component: <ThumbImg />

Renders the rasterized image for a thumbnail.

Hook: useThumbnailCapability()

Access the plugin API.

ThumbnailCapability Methods

ThumbnailScope Methods (Returned by forDocument)