Skip to content

Zoomist

A Vaadin Flow add-on that wraps the Zoomist JavaScript library to add interactive image zooming, dragging, and pinching.

Overview

Use the Zoomist add-on to turn any image into an interactive, zoomable view. Built on the Zoomist JavaScript library, it lets users zoom, drag, and pinch images, with full support for mobile and touch devices. The component exposes an optional zoomer control and slider, configurable fill modes and zoom ratios, programmatic zoom/move/reset actions, and a rich set of interaction event listeners.

Features

  • Zoom, drag, and pinch images.
  • Mobile and touch device support.
  • Optional on-screen zoomer control (zoom-in / zoom-out) and slider (horizontal or vertical).
  • Configurable image fill mode (COVER, CONTAIN, NONE).
  • Toggle draggable, wheelable (mouse-wheel zoom), pinchable, and out-of-bounds dragging.
  • Configurable zoom ratio and maximum ratio.
  • Programmatic control: zoom, move, moveTo, reset.
  • Query container data (width, height, aspect ratio).
  • Multiple image source types: URL string, DownloadHandler, or AbstractStreamResource.
  • Interaction listeners: ready, zoom, wheel, drag, slide, pinch, and resize.

Supported versions

Add-on version Vaadin version
1.x 24–25

Refer to the Vaadin Directory page for exact version compatibility.

Prerequisites

So that npm installs the bundled sass dependency correctly, create a .npmrc file in your project root containing:

legacy-peer-deps=true

Installation

From the Vaadin Directory

Available in the Vaadin Directory.

Maven dependency

<dependency>
    <groupId>com.flowingcode.vaadin.addons</groupId>
    <artifactId>zoomist-addon</artifactId>
    <version>X.Y.Z</version>
</dependency>

Replace X.Y.Z with the latest released version. Add the Vaadin add-ons repository to your pom.xml:

<repository>
    <id>vaadin-addons</id>
    <url>https://maven.vaadin.com/vaadin-addons</url>
</repository>

For snapshot builds, see maven.flowingcode.com/snapshots.

JavaDoc is published at javadoc.flowingcode.com.

Usage

Create a Zoomist from an image source:

Zoomist zoomist = new Zoomist("images/picture.jpg");
add(zoomist);

Configure the slider, zoomer, fill mode, and listen to interactions:

Zoomist zoomist = new Zoomist("images/helsinki.jpg");
zoomist.setSlider(null, Direction.VERTICAL, 10d);
zoomist.setZoomer(true);
zoomist.setDraggable(false);
zoomist.setFill(Fill.COVER);

zoomist.addDragStartListener(e ->
    Notification.show("Drag started at (" + e.getOffsetX() + ", " + e.getOffsetY() + ")"));
add(zoomist);

Control zoom programmatically and query container data:

zoomist.setZoomRatio(0.2);
zoomist.zoom(0.5); // zoom in by a relative ratio
zoomist.reset();   // back to the initial state

zoomist.getContainerData(data ->
    Notification.show("W=" + data.getWidth() + " H=" + data.getHeight()
        + " AR=" + data.getAspectRatio()));

Special configuration when using Spring

When running on Spring, allow-list the com.flowingcode package so Vaadin Flow can discover the add-on's components. See Common configuration for details.

API reference

Headline types exposed by the add-on:

  • Zoomist — the image component; extends Component. Constructors: Zoomist(String src), Zoomist(DownloadHandler src), Zoomist(AbstractStreamResource src). Key methods: setSrc(...), setSlider(...), setZoomer(...), setFill(Fill), flag setters (setDraggable, setWheelable, setPinchable, setBounds), setZoomRatio, setMaxRatio, actions (zoom, move, moveTo, reset), getContainerData(...), and listeners (addReadyListener, addZoomListener, addWheelListener, addDragStartListener/addDragListener/addDragEndListener, addSlideStartListener/addSlideListener/addSlideEndListener, addPinchStartListener/addPinchListener/addPinchEndListener, addResizeListener).
  • Zoomist.Fill — enum of fill modes (COVER, CONTAIN, NONE).
  • Zoomist.Direction — enum of slider directions (HORIZONTAL, VERTICAL).
  • ContainerData — holds width, height, and aspectRatio.

For the full API surface, browse the published JavaDoc.

Demo

A live demo is available at addonsv25.flowingcode.com/zoomist. To run the demo locally:

git clone https://github.com/FlowingCode/Zoomist.git
cd Zoomist
mvn clean install jetty:run

Then open http://localhost:8080/.

Source code

Zoomist on GitHub — distributed under Apache License 2.0.