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:
Function to initialize zoom on a container element. Call this function with a container ref after the component mounts.The container element that wraps the image element
Configuration options for the zoom behavior
zoomImageState
ZoomImageWheelState
required
Reactive state object that updates when zoom changes occurCurrent zoom level (1 = 100%, 2 = 200%, etc.)
Whether zoom functionality is currently enabled
Current X position of the zoomed image in pixels
Current Y position of the zoomed image in pixels
Current rotation angle in degrees
Function to get the current state imperatively. Returns the current ZoomImageWheelState or undefined if not initialized.
Function to programmatically update the zoom statestate
ZoomImageWheelStateUpdate
required
Partial state object to update
Options
Maximum zoom level allowed
Zoom sensitivity for mouse wheel events
Duration in milliseconds for double-tap zoom animation
initialState
Partial<ZoomImageWheelStateUpdate>
Initial state values for zoom, rotation, and position
Function that returns whether single-touch panning should be enabled. Defaults to always returning true.
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