Page Layout and Scroll Options in Our JavaScript Viewer

PSPDFKit for Web’s page layout options are based on the concept of spreads: Pages can be laid out one at a time or side by side in a double-page layout. For books and magazines that have a cover page, we support keeping the cover page in single-page layout, while laying out the following pages side by side in double-page layout. We call these groups of single- or double-pages spreads.

Spreads allow other view-related options to work with all layout modes.

We support changing between scrolling and viewing a single spread (single or double page) at any time.

All configuration happens by updating the ViewState. Please see our view state guide for more information.

Layout

With ViewState#layoutMode, you can define how pages are displayed within one spread:

  • Single Page Mode LayoutMode.SINGLE displays one page per spread. This is the default.

  • Double Page Mode LayoutMode.DOUBLE combines two pages on each spread. You can configure the spacing between the two pages with ViewState#pageSpacing and use ViewState#keepFirstSpreadAsSinglePage to make sure that the first spread only includes a single page.

  • Automatic Mode LayoutMode.AUTO is especially useful on tablets. It optimally utilizes the available space, showing either a single page or two pages side by side. For example, when the user rotates the device into landscape mode, it will automatically adjust and show two pages side by side. When the user rotates the device back to portrait mode, LayoutMode.AUTO will remember which of the two pages was previously shown and restore it.

Scrolling

ViewState#scrollMode defines how you transition between the pages in your document. We support three scrolling modes:

  • Continuous Scrolling ScrollMode.CONTINUOUS shows all spreads in a long, scrollable view. This is an experience similar to browsing a website and is the default mode. It is fully compatible with all our layout modes, and you can configure the distance between spreads using ViewState#spreadSpacing.

  • Per-Spread Scrolling ScrollMode.PER_SPREAD allows scrolling only within one spread. A spread is a collection of pages that depends on the current layout mode: For single-page layout, a spread contains one page, and for double-page layout it contains two. When a user moves between spreads, the zoom level of the view will be updated so that the entire next spread is visible again.

  • ScrollMode.DISABLED only allows scrolling within one spread, just like ScrollMode.PER_SPREAD does. However, it doesn’t allow navigating between pages via the UI. The only way to change the current page is through our programmatic API. When the spread changes, the zoom level of the view will be updated so that the entire spread is visible again. Please note that even though navigation is disabled through the UI, navigation to other pages can still occur, for instance, through link annotations present in the document. See the annotations.press event to learn how to prevent the action associated with an annotation.

Layout Configurator

If you want your users to be able to configure the layout themselves, you can add a layout options popover to the toolbar:

let toolbarItems = PSPDFKit.defaultToolbarItems;
// Add the `layout-config` toolbar item after the `pager` item.
let pagerIndex = toolbarItems.findIndex(item => item.type == "pager");
toolbarItems.splice(pagerIndex + 1, 0, { type: "layout-config" });

PSPDFKit.load({
  toolbarItems
  //...
});
var toolbarItems = PSPDFKit.defaultToolbarItems;
// Add the `layout-config` toolbar item after the `pager` item.
var pagerIndex = toolbarItems.findIndex(function(item) {
  return item.type == "pager";
});
toolbarItems.splice(pagerIndex + 1, 0, { type: "layout-config" });

PSPDFKit.load({
  toolbarItems: toolbarItems
  //...
});
The layout configurator allows your users to configure the layout on their own.