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'
// ... other imports
import { SpreadPluginPackage, SpreadMode } from '@embedpdf/plugin-spread/vue'
 
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 composable 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 composable 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.

<script setup lang="ts">
import { SpreadMode } from '@embedpdf/plugin-spread/vue';
import { useSpread } from '@embedpdf/plugin-spread/vue';
 
const { provides: spread, spreadMode } = useSpread();
 
const modes = [
  { label: 'Single Page', value: SpreadMode.None },
  { label: 'Two-Page (Odd)', value: SpreadMode.Odd },
  { label: 'Two-Page (Even)', value: SpreadMode.Even },
];
</script>
 
<template>
  <div v-if="spread" class="toolbar">
    <button
      v-for="mode in modes"
      :key="mode.value"
      @click="spread.setSpreadMode(mode.value)"
      :class="{ 'active': spreadMode === mode.value }"
    >
      {{ mode.label }}
    </button>
  </div>
</template>

Live Example

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

API Reference

Configuration (SpreadPluginConfig)

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