Skip to main content

​
Quickstart Guide

Get up and running with Zoom Image in just a few minutes. This guide will walk you through creating your first zoomable image.
Make sure you’ve installed Zoom Image before continuing.

​
Vanilla JavaScript

Let’s start with a simple vanilla JavaScript example using the wheel zoom mode:
1

Create your HTML structure

Create a container element with an image inside:
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Zoom Image Demo</title>
  <style>
    .zoom-container {
      width: 400px;
      height: 400px;
      cursor: crosshair;
      overflow: hidden;
      background: #000;
    }
    .zoom-container img {
      width: 100%;
      height: 100%;
      object-fit: contain;
    }
  </style>
</head>
<body>
  <div id="zoom-container" class="zoom-container">
    <img src="/your-image.jpg" alt="Zoomable image">
  </div>

  <script type="module" src="./main.js"></script>
</body>
</html>
2

Initialize zoom functionality

Import and initialize the zoom function in your JavaScript file:
main.js
import { createZoomImageWheel } from '@zoom-image/core';

const container = document.getElementById('zoom-container');

// Initialize zoom with options
const zoomImage = createZoomImageWheel(container, {
  maxZoom: 4,
  wheelZoomRatio: 0.1
});
That’s it! Your image is now zoomable. Try scrolling over it or pinch-zooming on mobile.
3

Add zoom controls (optional)

You can add buttons to control the zoom programmatically:
<div>
  <button id="zoom-in">Zoom In</button>
  <button id="zoom-out">Zoom Out</button>
  <p id="zoom-level">Zoom: 100%</p>
</div>
main.js
import { createZoomImageWheel } from '@zoom-image/core';

const container = document.getElementById('zoom-container');
const zoomImage = createZoomImageWheel(container, {
  maxZoom: 4,
  wheelZoomRatio: 0.1
});

// Subscribe to state changes
zoomImage.subscribe(({ state }) => {
  const zoomLevel = document.getElementById('zoom-level');
  zoomLevel.textContent = `Zoom: ${Math.round(state.currentZoom * 100)}%`;
});

// Zoom in button
document.getElementById('zoom-in').addEventListener('click', () => {
  const currentState = zoomImage.getState();
  zoomImage.setState({
    currentZoom: currentState.currentZoom + 0.5
  });
});

// Zoom out button
document.getElementById('zoom-out').addEventListener('click', () => {
  const currentState = zoomImage.getState();
  zoomImage.setState({
    currentZoom: currentState.currentZoom - 0.5
  });
});
4

Clean up on unmount

Remember to clean up when you’re done:
// When you need to destroy the zoom instance
zoomImage.cleanup();

​
React Example

For React applications, use the @zoom-image/react adapter for a more idiomatic experience:
1

Install the React adapter

npm install @zoom-image/core @zoom-image/react
2

Create a zoomable image component

App.tsx
import { useZoomImageWheel } from '@zoom-image/react';
import { useRef, useEffect } from 'react';

function ZoomableImage() {
  const containerRef = useRef<HTMLDivElement>(null);

  const {
    createZoomImage,
    zoomImageState,
    setZoomImageState
  } = useZoomImageWheel();

  useEffect(() => {
    if (containerRef.current) {
      createZoomImage(containerRef.current, {
        maxZoom: 4,
        wheelZoomRatio: 0.1
      });
    }
  }, [createZoomImage]);

  const zoomIn = () => {
    setZoomImageState({
      currentZoom: zoomImageState.currentZoom + 0.5
    });
  };

  const zoomOut = () => {
    setZoomImageState({
      currentZoom: zoomImageState.currentZoom - 0.5
    });
  };

  return (
    <div>
      <p>Current zoom: {Math.round(zoomImageState.currentZoom * 100)}%</p>
      <p>Scroll inside the image to zoom in/out</p>

      <div
        ref={containerRef}
        style={{
          width: '400px',
          height: '400px',
          cursor: 'crosshair',
          overflow: 'hidden'
        }}
      >
        <img
          src="/your-image.jpg"
          alt="Zoomable image"
          style={{ width: '100%', height: '100%' }}
        />
      </div>

      <div style={{ marginTop: '1rem', display: 'flex', gap: '0.5rem' }}>
        <button onClick={zoomIn}>Zoom In</button>
        <button onClick={zoomOut}>Zoom Out</button>
      </div>
    </div>
  );
}

export default ZoomableImage;
The React adapter automatically handles cleanup when the component unmounts.

​
Exploring Other Zoom Modes

Now that you have a basic wheel zoom working, try the other zoom modes:

​
Hover Zoom

Display a magnified view in a separate container: 
import { createZoomImageHover } from '@zoom-image/core';

const container = document.getElementById('image-container');
const zoomTarget = document.getElementById('zoom-target');

const zoomImage = createZoomImageHover(container, {
  zoomImageSource: '/high-res-image.jpg',
  customZoom: { width: 300, height: 500 },
  zoomTarget: zoomTarget,
  scale: 2
});

​
Move Zoom

Follow the cursor with a magnified view: 
import { createZoomImageMove } from '@zoom-image/core';

const container = document.getElementById('image-container');

const zoomImage = createZoomImageMove(container, {
  zoomImageSource: '/high-res-image.jpg'
});

​
Click Zoom

Toggle zoom on click: 
import { createZoomImageClick } from '@zoom-image/core';

const container = document.getElementById('image-container');

const zoomImage = createZoomImageClick(container, {
  zoomImageSource: '/high-res-image.jpg'
});

​
Advanced Features

​
Image Cropping

Capture the current zoomed view as a cropped image: 
import { createZoomImageWheel, cropImage } from '@zoom-image/core';

const container = document.getElementById('zoom-container');
const zoomImage = createZoomImageWheel(container);

// Crop at current zoom level
document.getElementById('crop-btn').addEventListener('click', async () => {
  const state = zoomImage.getState();
  const croppedImageSrc = await cropImage({
    image: container.querySelector('img'),
    currentZoom: state.currentZoom,
    positionX: state.currentPositionX,
    positionY: state.currentPositionY,
    rotation: state.currentRotation
  });

  // Use the cropped image
  const croppedImg = document.getElementById('cropped-result');
  croppedImg.src = croppedImageSrc;
});

​
Image Rotation

Rotate the image while maintaining zoom: 
const rotateButton = document.getElementById('rotate-btn');

rotateButton.addEventListener('click', () => {
  const currentState = zoomImage.getState();
  zoomImage.setState({
    currentRotation: currentState.currentRotation + 90
  });
});

​
State Management

All zoom functions return an object with these methods:
  • getState(): Get the current zoom state
  • setState(newState): Update the zoom state
  • subscribe(callback): Listen to state changes
  • cleanup(): Remove event listeners and clean up
const zoomImage = createZoomImageWheel(container);

// Get current state
const state = zoomImage.getState();
console.log(state.currentZoom); // e.g., 1.5

// Update state
zoomImage.setState({ currentZoom: 2 });

// Subscribe to changes
const unsubscribe = zoomImage.subscribe(({ state, prevState }) => {
  console.log('Zoom changed from', prevState.currentZoom, 'to', state.currentZoom);
});

// Cleanup
unsubscribe();
zoomImage.cleanup();

​
Next Steps

API Reference

Explore all configuration options

Framework Guides

Learn about framework-specific adapters

Examples

See more advanced implementations

Advanced Usage

Customize styling and behavior
Need help? Check out the full source code examples on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us