Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/willnguyen1312/zoom-image/llms.txt

Use this file to discover all available pages before exploring further.

​
Hook Signature

function useZoomImageWheel(): {
  createZoomImage: (
    container: HTMLElement,
    options?: ZoomImageWheelOptions
  ) => void
  zoomImageState: ZoomImageWheelState
  getZoomImageState: () => ZoomImageWheelState | undefined
  setZoomImageState: (state: ZoomImageWheelStateUpdate) => void
}

​
Return Value

The hook returns an object with the following properties:
​
createZoomImage
function
required
Function to initialize zoom on a container element. Call this function with a container ref after the component mounts.
​
container
HTMLElement
required
The container element that wraps the image element
​
options
ZoomImageWheelOptions
Configuration options for the zoom behavior
​
zoomImageState
ZoomImageWheelState
required
Reactive state object that updates when zoom changes occur
​
currentZoom
number
Current zoom level (1 = 100%, 2 = 200%, etc.)
​
enable
boolean
Whether zoom functionality is currently enabled
​
currentPositionX
number
Current X position of the zoomed image in pixels
​
currentPositionY
number
Current Y position of the zoomed image in pixels
​
currentRotation
number
Current rotation angle in degrees
​
getZoomImageState
function
required
Function to get the current state imperatively. Returns the current ZoomImageWheelState or undefined if not initialized.
​
setZoomImageState
function
required
Function to programmatically update the zoom state
​
state
ZoomImageWheelStateUpdate
required
Partial state object to update

​
Options

​
maxZoom
number
default:"4"
Maximum zoom level allowed
​
wheelZoomRatio
number
default:"0.1"
Zoom sensitivity for mouse wheel events
​
dblTapAnimationDuration
number
default:"300"
Duration in milliseconds for double-tap zoom animation
​
initialState
Partial<ZoomImageWheelStateUpdate>
Initial state values for zoom, rotation, and position
​
shouldZoomOnSingleTouch
() => boolean
Function that returns whether single-touch panning should be enabled. Defaults to always returning true.
​
zoomTarget
HTMLElement | null
Specific element to apply zoom transform to. Defaults to the first img element inside the container.

​
Example

import { useZoomImageWheel } from '@zoom-image/react'
import { useEffect, useRef } from 'react'

function ImageViewer() {
  const containerRef = useRef<HTMLDivElement>(null)
  const {
    createZoomImage,
    zoomImageState,
    setZoomImageState,
  } = useZoomImageWheel()

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

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

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

  const rotate = () => {
    setZoomImageState({
      currentRotation: zoomImageState.currentRotation + 90,
    })
  }

  return (
    <div>
      <p>Current zoom: {Math.round(zoomImageState.currentZoom * 100)}%</p>
      
      <div 
        ref={containerRef} 
        className="h-[300px] w-[200px] cursor-crosshair"
      >
        <img 
          className="h-full w-full" 
          alt="Zoomable image" 
          src="/image.jpg" 
        />
      </div>

      <div className="flex gap-2 mt-4">
        <button onClick={zoomIn}>Zoom In</button>
        <button onClick={zoomOut}>Zoom Out</button>
        <button onClick={rotate}>Rotate</button>
      </div>
    </div>
  )
}

​
Cleanup

The hook automatically cleans up event listeners and subscriptions when the component unmounts. You don’t need to manually call cleanup.

​
See Also