Tiling Plugin

The Tiling Plugin is a performance optimization that can dramatically improve the user experience for large documents or at high zoom levels.

Instead of rendering a page as one large image, this plugin breaks it into a grid of smaller tiles. It then intelligently renders only the tiles currently visible in the viewport, reducing memory usage and speeding up render times. This technique is similar to how online maps work, loading content as you pan and zoom.

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/svelte'
import { ScrollPluginPackage } from '@embedpdf/plugin-scroll/svelte'
import { RenderPluginPackage } from '@embedpdf/plugin-render/svelte'
import { TilingPluginPackage } from '@embedpdf/plugin-tiling/svelte'
 
const plugins = [
  // ... other essential plugins
  // Register dependencies first
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),
 
  // Register and configure the tiling plugin
  createPluginRegistration(TilingPluginPackage, {
    tileSize: 768,
    overlapPx: 5,
    extraRings: 1, // Pre-render one ring of tiles outside the viewport
  }),
]

Usage

The best way to use the Tiling plugin is to adopt a two-layer rendering strategy. This provides the best user experience by showing a fast, low-resolution preview immediately, then progressively enhancing it with high-resolution tiles.

You achieve this by rendering both a <RenderLayer /> and a <TilingLayer />:

1. <RenderLayer />: Use this for the base layer. Give it a low, fixed scale prop (e.g., 0.5 or 1) so it renders a blurry but complete preview of the page very quickly.
2. <TilingLayer />: Place this on top of the base layer. It receives the dynamic scale prop from the scroller and will render the crisp, high-resolution tiles over the blurry preview.

<script lang="ts">
import { RenderLayer } from '@embedpdf/plugin-render/svelte';
import { TilingLayer } from '@embedpdf/plugin-tiling/svelte';
</script>
 
{#snippet RenderPageSnippet(page)}
  <div style:width={`${page.width}px`} style:height={`${page.height}px`} style:position="relative">
    <!-- 1. Low-resolution base layer for immediate feedback -->
    <RenderLayer pageIndex={page.pageIndex} scale={1} />
    <!-- 2. High-resolution tile layer on top -->
    <TilingLayer pageIndex={page.pageIndex} scale={page.scale} />
  </div>
{/snippet}
 
<Scroller {RenderPageSnippet} />

Live Example

This example uses the <TilingLayer /> for rendering. Zoom in significantly on the document to see the tiles being rendered individually. You may notice a brief low-resolution version of a tile before the high-resolution version loads in.

API Reference

Configuration (TilingPluginConfig)

Component: <TilingLayer />

The component that orchestrates the rendering of individual tiles for a page.