Skip to main content
The ZoomImageWheelOptions type defines the configuration options for creating a wheel-based zoom interface that supports mouse wheel zooming, pinch-to-zoom gestures, and touch interactions.

​
Type Definition

type ZoomImageWheelOptions = {
  maxZoom?: number
  wheelZoomRatio?: number
  dblTapAnimationDuration?: number
  initialState?: Partial<ZoomImageWheelStateUpdate>
  shouldZoomOnSingleTouch?: () => boolean
  zoomTarget?: HTMLElement | null
}

​
Properties

​
maxZoom
number
default:"4"
The maximum zoom level allowed. The zoom scale is clamped between 1 (original size) and this value.Example:
maxZoom: 6 // Allow zooming up to 6x the original size
​
wheelZoomRatio
number
default:"0.1"
Controls the sensitivity of wheel-based zooming. Higher values result in faster zoom on each wheel event.Example:
wheelZoomRatio: 0.2 // Faster zoom speed
​
dblTapAnimationDuration
number
default:"300"
Duration in milliseconds for the double-tap zoom animation. Controls how quickly the image animates between zoomed and unzoomed states.Example:
dblTapAnimationDuration: 500 // Slower, smoother animation
​
initialState
Partial<ZoomImageWheelStateUpdate>
Initial state for the zoom component. Allows you to set the starting zoom level, rotation, or enable/disable state.Properties:
  • enable?: boolean - Whether zoom is initially enabled (default: true)
  • currentZoom?: number - Initial zoom level (default: 1)
  • currentRotation?: number - Initial rotation in degrees (default: 0)
  • zoomTarget?: HTMLElement | null - Target element to apply zoom transform
Example:
initialState: {
  currentZoom: 2,
  currentRotation: 90,
  enable: true
}
​
shouldZoomOnSingleTouch
() => boolean
default:"() => true"
Callback function that determines whether single-touch gestures should trigger zoom behavior. Useful for conditionally enabling/disabling touch zoom.Example:
shouldZoomOnSingleTouch: () => {
  // Only allow zoom on touch devices in landscape mode
  return window.innerWidth > window.innerHeight
}
​
zoomTarget
HTMLElement | null
The HTML element to apply zoom transformations to. If not provided, defaults to the first <img> element within the container.Example:
const customTarget = document.querySelector('.zoom-image')
zoomTarget: customTarget

​
ZoomImageWheelState

The internal state managed by the zoom component: 
type ZoomImageWheelState = {
  currentRotation: number    // Current rotation angle in degrees
  currentZoom: number        // Current zoom level (1 = original size)
  enable: boolean            // Whether zoom interactions are enabled
  currentPositionX: number   // X-axis position offset in pixels
  currentPositionY: number   // Y-axis position offset in pixels
}

​
ZoomImageWheelStateUpdate

Partial state updates that can be applied: 
type ZoomImageWheelStateUpdate = Partial<{
  enable: boolean
  currentZoom: number
  currentRotation: number
  zoomTarget: HTMLElement | null
}>

​
Usage Example

import { createZoomImageWheel } from '@zoom-image/core'

const container = document.querySelector('.image-container')

const zoomInstance = createZoomImageWheel(container, {
  maxZoom: 5,
  wheelZoomRatio: 0.15,
  dblTapAnimationDuration: 400,
  initialState: {
    enable: true,
    currentZoom: 1
  },
  shouldZoomOnSingleTouch: () => true
})

// Subscribe to state changes
zoomInstance.subscribe((state) => {
  console.log('Current zoom:', state.currentZoom)
  console.log('Position:', state.currentPositionX, state.currentPositionY)
})

// Update state programmatically
zoomInstance.setState({
  currentZoom: 3,
  currentRotation: 90
})

// Clean up when done
zoomInstance.cleanup()

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us