Spread Plugin

The Spread Plugin controls the page layout, allowing you to switch between a single-page view and a two-page “spread” view, similar to an open book. This plugin is purely logical; it changes how pages are grouped before being rendered, without providing any UI components itself.

Installation

The plugin is available as a separate NPM package.

npm install @embedpdf/plugin-spread

pnpm add @embedpdf/plugin-spread

yarn add @embedpdf/plugin-spread

bun add @embedpdf/plugin-spread

Registration

Import SpreadPluginPackage and add it to the plugins array. You can configure the default layout mode when the viewer loads.

import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import { SpreadPluginPackage, SpreadMode } from '@embedpdf/plugin-spread/react'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),
 
  // Register and configure the spread plugin
  createPluginRegistration(SpreadPluginPackage, {
    defaultSpreadMode: SpreadMode.None,
  }),
]

Usage

The plugin provides the useSpread hook to control the layout mode. When you change the mode, the plugin recalculates the page groupings, and the <Scroller> component automatically updates to reflect the new layout.

Building a Spread Mode Toolbar

Use the useSpread hook to get the current spreadMode and the provides object for changing it. You can then build a UI, like a set of buttons, to allow users to switch between layouts.

import { SpreadMode } from '@embedpdf/plugin-spread';
import { useSpread } from '@embedpdf/plugin-spread/react';
 
export const SpreadToolbar = () => {
  const { provides: spread, spreadMode } = useSpread();
 
  if (!spread) return null;
 
  return (
    <div>
      <span>Current Layout: {spreadMode}</span>
      <button onClick={() => spread.setSpreadMode(SpreadMode.None)}>Single Page</button>
      <button onClick={() => spread.setSpreadMode(SpreadMode.Odd)}>Two-Page (Odd)</button>
      <button onClick={() => spread.setSpreadMode(SpreadMode.Even)}>Two-Page (Even)</button>
    </div>
  );
};

Live Example

This example shows a viewer with a toolbar that lets you dynamically change the page layout.

API Reference

Configuration (SpreadPluginConfig)

Hook: useSpread()

Connects your component to the spread plugin’s state and functions.

Returns

SpreadCapability Methods

SpreadMode Enum

The SpreadMode determines how pages are grouped together.