Zoom options in our JavaScript PDF viewer

Nutrient Web SDK features different UI elements and API helpers to both manage zooming in and out of a document and handle zooming automatically.

Zooming with the UI

Documents opened in Nutrient Web SDK’s viewer can be zoomed in on and out of using the corresponding toolbar buttons, zoom-in and zoom-out:

Zooming can also be controlled using keyboard shortcuts:

Control/Command + + — Zoom in
Control/Command + - — Zoom out
Control/Command + 0 — Zoom to auto
Control + Scroll wheel — Zoom in or out at mouse position

The zoom-mode button can be used to toggle the current zoom so that the page fits either the viewport width or the viewport height.

Zoom Mode button: toggles page fitting to the viewport width or height.

The marquee-zoom button, hidden by default, can be used to zoom to the area of a rectangle drawn by the user.

Marquee Zoom button: enables drawing of rectangle to zoom to.

The marquee-zoom button is enabled in the PSPDFKit.Configuration object passed to PSPDFKit.load():

PSPDFKit.load({
  toolbarItems: PSPDFKit.defaultToolbarItems.concat([
    { type: "marquee-zoom" }
  ])
});

Or, it can be enabled using the instance.setToolbarItems() API method:

instance.setToolbarItems((items) =>
  items.concat([{ type: "marquee-zoom" }])
);

Zooming with the API

Configuring zoom behavior

Control the zoom configuration granularly using the ZoomConfiguration object.

The zoom setting can be passed to PSPDFKit.Configuration#initialViewState when loading the viewer:

PSPDFKit.load({
  initialViewState: new PSPDFKit.ViewState({
    zoom: {
      // Set the zoom mode or numeric value.
      zoomMode: PSPDFKit.ZoomMode.FIT_TO_WIDTH,

      // Configure scroll wheel zoom behavior.
      wheelZoomMode: PSPDFKit.WheelZoomMode.ALWAYS,

      // Configure zoom options.
      options: {
        enableKeyboardZoom: true,
        enableGestureZoom: true
      }
    }
  })
});

This can also be changed after initialization using setViewState:

instance.setViewState(new PSPDFKit.ViewState({
  zoom: {
    // Set the zoom mode or numeric value.
    zoomMode: PSPDFKit.ZoomMode.FIT_TO_WIDTH,

    // Configure scroll wheel zoom behavior.
    wheelZoomMode: PSPDFKit.WheelZoomMode.ALWAYS,

    // Configure zoom options.
    options: {
      enableKeyboardZoom: true,
      enableGestureZoom: true
      }
    }
  });
);

To ensure backward compatibility, the zoom property of the viewState accepts a ZoomConfiguration, or a ZoomMode, or a number:

// Pass a `zoomMode` to zoom.

PSPDFKit.load({
  initialViewState: new PSPDFKit.ViewState({
    zoom: PSPDFKit.ZoomMode.FIT_TO_WIDTH
  })
});

// Pass a number to zoom.

PSPDFKit.load({
  initialViewState: new PSPDFKit.ViewState({
    zoom: 7
  })
});

Available zoom modes

The following zoom modes are available through PSPDFKit.ZoomMode:

AUTO will automatically align the page for the best viewing experience.
FIT_TO_WIDTH will fit the width of the broadest page into the viewport. The height might overflow.
FIT_TO_VIEWPORT will fit the current page into the viewport completely.

instance.setViewState(new PSPDFKit.ViewState({
  zoom: {
    // Set the zoom mode.
    zoomMode: PSPDFKit.ZoomMode.FIT_TO_WIDTH,

    // Other zoom configurations.
    }
  });
);

You can also specify a numeric zoom value instead of a mode:

PSPDFKit.load({
  initialViewState: new PSPDFKit.ViewState({
    zoom: {
      // Set the zoom to a numeric value.
      zoomMode: 7
      // Other zoom configurations.
    }
  })
});

Zooming at mouse position with the scroll wheel

Nutrient Web SDK now offers three modes for scroll wheel zoom behavior, defined in WheelZoomMode:

WITH_CTRL (default) — Zoom when Control + scroll wheel is used.
ALWAYS — Always zoom on scroll wheel without requiring the Control key to be pressed.
DISABLED — Completely disable scroll wheel zooming regardless of which key is pressed.

Configure this behavior when loading the viewer:

PSPDFKit.load({
  // ...
  initialViewState: new PSPDFKit.ViewState({
    zoom: {
      wheelZoomMode: PSPDFKit.WheelZoomMode.WITH_CTRL,
      // Other zoom configurations.
    },
  });
});

Or, change it after initialization:

instance.setViewState(new PSPDFKit.ViewState({
  zoom: {
    wheelZoomMode: PSPDFKit.WheelZoomMode.WITH_CTRL,
    // Other zoom configurations.
    },
  });
);

This change deprecates PSPDFKit.ViewState#enableAlwaysScrollToZoom.

Zoom options

enableKeyboardZoom — Enables zooming via keyboard shortcuts (Control/Command + [+-]). Defaults to true.
enableGestureZoom — Enable zooming via touch gestures. Defaults to true.

PSPDFKit.load({
  initialViewState: new PSPDFKit.ViewState({
    zoom: {
      // Other zoom configurations.

      // Configure zoom options.
      options: {
        enableKeyboardZoom: false,
        enableGestureZoom: false
      }
    }
  })
});

Changing zoom scale increments

By default, each click on the zoom toolbar buttons increases or decreases the zooming scale by increments of 25 percent. To change this default zoom step, change the zoomStep property of the viewState object. Use a number greater than 1.

The example below changes the zoom step to 10 percent:

instance.setViewState((viewState) => viewState.set("zoomStep", 1.1));

Querying current zoom values

The current zoom value can be queried with instance.currentZoomLevel at any time.

Other dynamic values related to zooming available in the current instance are:

instance.minimumZoomLevel — Minimum zoom level attainable using the UI or the API.
instance.maximumZoomLevel — Maximum zoom level attainable using the UI or the API.

API zooming helpers

The API provides some helpers to make programmatic zoom handling easier.

This example zooms in to the document by a single step via PSPDFKit.ViewState#zoomIn():

instance.setViewState((viewState) => viewState.zoomIn());

It has its counterpart, PSPDFKit.ViewState#zoomOut():

instance.setViewState((viewState) => viewState.zoomOut());

Finally, instance.jumpAndZoomToRect() can zoom to any part of the document.

This example navigates to page 10 of the document and zooms in to the bounding box of an annotation, making it take the whole viewport size:

instance.jumpAndZoomToRect(10, annotation.boundingBox);

When the zoom value changes, the page background may be rendered again to keep showing a sharp image.

Preventing zooming for annotations

By default, each annotation’s appearance scales to match the page zoom. To change this behavior, the noZoom flag can be set to true to prevent an annotation from being magnified when zooming in. This is currently only enabled for StampAnnotation and TextAnnotation, with the exception of TextAnnotations with the callout property set.

The example below creates a TextAnnotation with the noZoom flag set to true:

await instance.create([
  new PSPDFKit.Annotations.TextAnnotation({
    pageIndex: 0,
    boundingBox: new PSPDFKit.Geometry.Rect({
      left: 50,
      top: 150,
      width: 180,
      height: 25
    }),
    text: {
      format: "plain",
      value: "Text with noZoom flag"
    },
    noZoom: true
  })
]);