Render Plugin

The Render Plugin is the visual heart of the PDF viewer. It is responsible for taking the raw PDF data from the core engine and “painting” it onto the screen. It supports high-fidelity rendering of text, images, vector graphics, and form widgets.

This plugin works seamlessly in multi-document environments, allowing you to render pages from different documents simultaneously using specific documentId references.

Installation

The plugin is available as a separate NPM package and is essential for any visual viewer.

npm install @embedpdf/plugin-render

pnpm add @embedpdf/plugin-render

yarn add @embedpdf/plugin-render

bun add @embedpdf/plugin-render

Registration

Import RenderPluginPackage and add it to the plugins array. You can configure global defaults for form and annotation rendering here.

import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import { RenderPluginPackage } from '@embedpdf/plugin-render/react'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(DocumentManagerPluginPackage, { /* ... */ }),
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),
 
  // Register the render plugin
  createPluginRegistration(RenderPluginPackage, {
    // Optional: Draw form widget visuals (checkboxes, text content)
    // Note: This is for display only, not interaction.
    withForms: true, 
    // Optional: Burn annotations into the render (usually handled by AnnotationPlugin instead)
    withAnnotations: false, 
  }),
]

Usage

The plugin allows you to render pages declaratively via the <RenderLayer /> component or imperatively via the useRenderCapability hook (e.g., for exporting images).

Primary Usage: The <RenderLayer /> Component

This is the standard way to display a page. Place the <RenderLayer /> component inside the renderPage prop of your <Scroller />.

You must provide the documentId to tell the renderer which document the page belongs to. The component automatically detects the current scale and refresh version from the document state.

<Scroller
  documentId={activeDocumentId}
  renderPage={({ pageIndex }) => (
    <div style={{ position: 'relative' }}>
      {/* The RenderLayer is responsible for drawing the page */}
      <RenderLayer 
        documentId={activeDocumentId} 
        pageIndex={pageIndex} 
      />
    </div>
  )}
/>

Advanced Usage: On-Demand Rendering

For tasks like generating thumbnails, creating snapshots, or exporting pages as images, use the useRenderCapability hook.

Because multiple documents may be open, you must scope your request using .forDocument(id).

import { useRenderCapability } from '@embedpdf/plugin-render/react';
 
const ExportButton = ({ documentId }) => {
  const { provides: renderPlugin } = useRenderCapability();
 
  const exportPage = () => {
    // 1. Scope the renderer to the specific document
    const renderer = renderPlugin?.forDocument(documentId);
 
    // 2. Request a render
    const task = renderer?.renderPage({ 
      pageIndex: 0, 
      options: { scaleFactor: 2.0, imageType: 'image/png' } 
    });
 
    task?.wait(blob => {
      // ... handle the image blob (e.g., download it)
    });
  };
 
  return <button onClick={exportPage}>Export Page 1</button>
}

Live Example

This example shows a PDF viewer with a custom “Export” toolbar. It uses the RenderPlugin to take a high-resolution snapshot of the first page, including annotations, and triggers a download.

API Reference

Configuration (RenderPluginConfig)

Component: <RenderLayer />

The component that renders a single PDF page.

Hook: useRenderCapability()

Access the rendering API.

Returns

RenderCapability Methods

RenderScope Methods (Returned by forDocument)

PdfRenderPageOptions