EmbedPDF
DocsSveltePluginsTiling

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

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
  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.

<script lang="ts">
import { Scroller, type RenderPageProps } from '@embedpdf/plugin-scroll/svelte';
import { RenderLayer } from '@embedpdf/plugin-render/svelte';
import { TilingLayer } from '@embedpdf/plugin-tiling/svelte';
 
let { documentId }: { documentId: string } = $props();
</script>
 
{#snippet renderPage(page: RenderPageProps)}
  <div style:width="{page.width}px" style:height="{page.height}px" style:position="relative">
    <!-- 1. Low-resolution base layer for immediate feedback -->
    <!-- We fix the scale at 1.0 (or lower) regardless of zoom -->
    <RenderLayer 
      {documentId}
      pageIndex={page.pageIndex} 
      scale={1.0} 
    />
 
    <!-- 2. High-resolution tile layer on top -->
    <!-- This automatically uses the current zoom level from the document state -->
    <TilingLayer 
      {documentId}
      pageIndex={page.pageIndex} 
    />
  </div>
{/snippet}
 
<Scroller {documentId} {renderPage} />

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)

OptionTypeDescription
tileSizenumberThe width and height of each square render tile in screen pixels.
Default: 768
overlapPxnumberThe number of pixels each tile should overlap its neighbors to prevent visible seams (white lines) between them.
Default: 2.5
extraRingsnumberThe number of “rings” of tiles to pre-render outside the visible viewport. Increasing this makes scrolling smoother but increases memory usage.
Default: 0

Component: <TilingLayer />

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

PropTypeDescription
documentIdstring(Required) The ID of the document this page belongs to.
pageIndexnumber(Required) The 0-based index of the page to render.
scalenumberOptional scale override. If omitted, uses the document’s current zoom level.

Store: useTilingCapability()

Access the tiling API.

TilingCapability Methods

MethodDescription
forDocument(id)Returns a TilingScope for the specified document ID.
onTileRendering(cb)Event hook that fires whenever the set of visible tiles changes for any document.

TilingScope Methods (Returned by forDocument)

MethodDescription
renderTile(options)Manually requests a tile render. Used internally by the component.
Last updated on December 5, 2025
RenderThumbnail

Need Help?

Join our community for support, discussions, and to contribute to EmbedPDF's development.

GitHub DiscussionsDiscord CommunitySupport Development