use-pinch-zoom

usePinchZoom hook

This is a react hook that allows you to zoom and drag using touch gestures and mouse events.

Demo

https://use-pinch-zoom.vercel.app/

Setup

To run this project, install it locally using npm:

npm i use-pinch-zoom

Quick start

1. Import the “usePinchZoom” hook:

import usePinchZoom from "use-pinch-zoom";

const {
  pinchZoomTransitionX,
  pinchZoomTransitionY,
  onMouseDown,
  onDragStart,
  isDragging,
  zoom,
  onDraging,
  onTouchEnd,
  onMouseWheel,
} = usePinchZoom({});

2. Assign event functions and pinchZoomTransitionX, pinchZoomTransitionY, zoom as CSS style properties to the elements you want to zoom.

<img
  onMouseDown={onMouseDown}
  onTouchMove={onDraging}
  onTouchEnd={onTouchEnd}
  onTouchStart={onDragStart}
  onWheel={onMouseWheel}
  style={{
    transform: `scale(${zoom}) translateX(${pinchZoomTransitionX}px) translateY(${pinchZoomTransitionY}px)`,
  }}
/>

3. By default, this feature disables the browser's native zooming and scrolling during pinch zoom or drag when the zoom level is higher than 1. This means that when the zoom level is set to 1, you can still zoom on the page using native pinch zoom when your fingers are not on the element that supports this function. When the zoom level exceeds 1, the feature will prevent native zooming and scrolling of the entire document. However, this can be disabled using the "preventDefaultTouchBehavior" and "preventDefaultWheelBehavior" properties.

4. If you want to disable native zooming and scrolling for the entire document or content, such as a modal, you can add the CSS style "touch-action: none" to the "body" tag or modal container. If you want to disable native pinch zoom but still be able to scroll vertically and horizontally, you can set "touch-action: pan-y pan-x".

5. In order for the function to calculate everything correctly (margins, etc.), the enlarged element must always be centered relative to its parent or fill it completely. If you do not want the element that you are zooming in on to be centered in relation to the viewport, you can still achieve this. Simply wrap your element in a container that will either center it or completely fill it. Set the property "relativeTo" to "parent" or "both". You can place the container anywhere on the screen (left-aligned, right-aligned) and everything should work as intended.

 

Usage details

Property	Default	Type	Details
boundaryResistance?	50	number	How far you can drag the zoomed element out of scope.
maxZoom?	3	number	Maximum zoom value.
doubleTapSensivity?	300(ms)	number	Double tap sensivity.
minDistBetweenFingers?	80(px)	number	The minimum distance between fingers that allows for zooming with two fingers.
keepZoom?	true	boolean	You can set this to false if you want after touchend zoom return to the initial position.
disableDoubleTap?	false	boolean	You can set this option to true if you want to disable double-tap zoom.
zoomFactor?	4	number	Defines how many times the increaseZoom function will need to be called to obtain the maximum zoom. For example, if you set 5, each function call will increase the element by 20 percent of its size.
relativeTo?	"viewport"	"viewport", "parent", "both"	Specifies the element against which the boundaries will be set and the zoom calculations will be performed. It is important to keep in mind that the enlarged element should always be centered in relation to its parent. The default value is "viewport". You have the option to pass different values here, such as: "viewport", "parent", "both". If you choose "both", it means that the element will be positioned relative to the parent when it exceeds the parent's size, and relative to the viewport when it exceeds the viewport's size. This option combines the "parent" and "viewport" values and keeps track of both parent and viewport boundaries.
allowDragWhenZooming?	true	boolean	It defines whether you can move an element during pinch zoom.
preventDefaultTouchBehavior?	true	boolean	Prevents the default pinch zoom and scroll functionality of the web browser when an element is enlarged with two fingers or when the zoom level is greater than 1.
preventDefaultWheelBehavior?	true	boolean	Prevents the default scroll functionality of the web browser when the zoom level of an element is greater than 1.

 

Functions and variables that return a hook.

Function	Type	Usage
onMouseDown	function	Function to handle "onMouseDown" event.
onDragStart	function	Function to handle "onTouchStart" event.
onDragging	function	Function to handle "onTouchMove" event.
onTouchEnd	function	Function to handle "onTouchEnd" event.
onTouchEnd	function	Function to handle "onTouchEnd" event.
onMouseWheel	function	Function to handle "onWheel" event. You should add this if you want to be able to scroll the zoomed element using the mouse wheel.
handleDecreaseZoom	function	Call this function to decrease the zoom.
handleIncreaseZoom	function	Call this function to increase the zoom.
handleResetZoom	function	Call this function to reset the zoom/translation to its initial values.
enableDragAndZoom	function	Call this function to enable zooming/dragging.
disableDragAndZoom	function	Call this function to disable zooming/dragging.
pinchZoomTransitionX	number	Add this as a transform css property to your zoom element.
pinchZoomTransitionY	number	Add this as a transform css property to your zoom element.
zoom	number	Add this as css property to your zoom element.
isDragging	boolean	Changes the value to true when dragging.
isZooming	boolean	Changes the value to true when zooming with two fingers.
wasDoubleTapped	boolean	Changes the value to true after double tap.

 

 

Example on Codesandbox

https://codesandbox.io/p/sandbox/usepinchzoom-mj589m