Hook Signature
function useZoomImageHover(): {
createZoomImage: (
container: HTMLElement,
options: ZoomImageHoverOptions
) => void
zoomImageState: ZoomImageHoverState
setZoomImageState: (state: ZoomImageHoverStateUpdate) => void
}
Return Value
The hook returns an object with the following properties:
Function to initialize hover zoom on a container element. Must be called with both container and options.The container element that wraps the source image
options
ZoomImageHoverOptions
required
Configuration options for the hover zoom effect
zoomImageState
ZoomImageHoverState
required
Reactive state object that updates during hover interactionsWhether hover zoom is currently enabled
zoomedImgStatus
'idle' | 'loading' | 'loaded' | 'error'
Loading status of the zoomed image
Function to programmatically enable or disable hover zoomstate
ZoomImageHoverStateUpdate
required
State update object with enabled property
Options
The element where the zoomed image will be displayed. This is typically positioned beside or overlaying the source image.
customZoom
{ width: number; height: number }
required
Dimensions of the zoom target area in pixels
URL of the high-resolution image to display in the zoom target. Defaults to the source image’s src.
Magnification scale factor. A value of 2 means the zoomed image appears at 200% size.
CSS class name(s) to apply to the hover lens overlay
Scale factor for the lens size relative to the zoom target
CSS class name(s) to apply to the zoom target element when active
If true, allows page scrolling while hovering over the image
Additional props for the zoomed image elementAlt text for the zoomed image
Example
import { useZoomImageHover } from '@zoom-image/react'
import { useEffect, useRef } from 'react'
function ProductImage() {
const containerRef = useRef<HTMLDivElement>(null)
const zoomTargetRef = useRef<HTMLDivElement>(null)
const { createZoomImage, zoomImageState } = useZoomImageHover()
useEffect(() => {
if (containerRef.current && zoomTargetRef.current) {
createZoomImage(containerRef.current, {
zoomImageSource: '/product-image-large.jpg',
customZoom: { width: 400, height: 600 },
zoomTarget: zoomTargetRef.current,
scale: 2,
})
}
}, [])
return (
<div className="flex gap-8">
<div
ref={containerRef}
className="relative h-[300px] w-[200px]"
>
<img
className="h-full w-full"
alt="Product thumbnail"
src="/product-image-small.jpg"
/>
</div>
<div ref={zoomTargetRef} className="border border-gray-300" />
</div>
)
}
Custom Lens Styling
You can customize the appearance of the hover lens using the zoomLensClass option:
useEffect(() => {
if (containerRef.current && zoomTargetRef.current) {
createZoomImage(containerRef.current, {
zoomImageSource: '/image-large.jpg',
customZoom: { width: 400, height: 600 },
zoomTarget: zoomTargetRef.current,
scale: 2,
zoomLensClass: 'border-2 border-blue-500 bg-blue-100/20',
})
}
}, [])
Cleanup
The hook automatically cleans up event listeners, DOM elements, and subscriptions when the component unmounts. Manual cleanup is not required.
See Also