Tiling Plugin

The Tiling Plugin is a performance optimization tool designed for large documents or high-zoom scenarios.

Instead of rendering a page as one massive image canvas (which can crash browsers at high zoom levels), this plugin breaks the page into a grid of smaller tiles. It intelligently renders only the tiles currently visible in the viewport, significantly reducing memory usage and keeping the UI responsive.

This plugin supports multi-document layouts, managing tile grids and render queues independently for every open document.

Installation

The plugin depends on the Render, Scroll, and Viewport plugins. You must install all four packages.

npm install @embedpdf/plugin-tiling @embedpdf/plugin-render @embedpdf/plugin-scroll @embedpdf/plugin-viewport

pnpm add @embedpdf/plugin-tiling @embedpdf/plugin-render @embedpdf/plugin-scroll @embedpdf/plugin-viewport

yarn add @embedpdf/plugin-tiling @embedpdf/plugin-render @embedpdf/plugin-scroll @embedpdf/plugin-viewport

bun add @embedpdf/plugin-tiling @embedpdf/plugin-render @embedpdf/plugin-scroll @embedpdf/plugin-viewport

Registration

Import TilingPluginPackage and its dependencies, and add them to the plugins array. The Tiling plugin should be registered after the plugins it depends on.

import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/vue'
import { ScrollPluginPackage } from '@embedpdf/plugin-scroll/vue'
import { RenderPluginPackage } from '@embedpdf/plugin-render/vue'
import { TilingPluginPackage } from '@embedpdf/plugin-tiling/vue'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),
 
  // Register and configure the tiling plugin
  createPluginRegistration(TilingPluginPackage, {
    tileSize: 768, // Size of each tile in pixels
    overlapPx: 5,  // Overlap to prevent visible seams
    extraRings: 0, // Pre-render tiles just outside the viewport
  }),
]

Usage

The most effective rendering strategy combines a base layer with a tiling layer.

1. Base Layer (<RenderLayer />): Renders a low-resolution version of the entire page immediately. This prevents the user from seeing white space while tiles load.
2. Tiling Layer (<TilingLayer />): Placed on top of the base layer. It renders high-resolution tiles only for the visible area.

You must provide the documentId to both components so they connect to the correct document state.

<template>
  <Scroller :document-id="activeDocumentId">
    <template #default="{ page }">
      <div :style="{ width: `${page.width}px`, height: `${page.height}px`, position: 'relative' }">
        <!-- 1. Low-resolution base layer for immediate feedback -->
        <!-- We fix the scale at 1.0 (or lower) regardless of zoom -->
        <RenderLayer 
          :document-id="activeDocumentId"
          :page-index="page.pageIndex" 
          :scale="1.0" 
        />
 
        <!-- 2. High-resolution tile layer on top -->
        <!-- This automatically uses the current zoom level from the document state -->
        <TilingLayer 
          :document-id="activeDocumentId"
          :page-index="page.pageIndex" 
        />
      </div>
    </template>
  </Scroller>
</template>

Live Example

This example demonstrates the tiling effect. Use the controls to zoom in deeply; the viewer remains responsive because it is rendering small tiles rather than a giant canvas.

API Reference

Configuration (TilingPluginConfig)

Component: <TilingLayer />

The component that manages the grid of <TileImg /> components for a page.

Composable: useTilingCapability()

Access the tiling API.

TilingCapability Methods

TilingScope Methods (Returned by forDocument)