DOCSEARCHbyAlgolia
Submit Docs

react-native-image-zoom

repository·main·Indexed 19 days ago

https://github.com/likashefqet/react-native-image-zoom

A performant and customizable image zoom component for React Native built with Reanimated v2+ and TypeScript. It supports pinch, pan, single tap, and double tap gestures. The library provides the ImageZoom component for standard images, a Zoomable wrapper for custom components (such as expo-image or react-native-fast-image), and hooks like useZoomable, useZoomableHandle, and useZoomableLayout for advanced implementation and programmatic control.

Tokens
5.3K
Snippets
14
Records
17
Agent score
68%

What's inside @likashefqet/react-native-image-zoom

  1. Make custom components zoomable

    main

    The library allows you to wrap any child element to make it behave like a zoomable image. This is useful when using alternative image components like expo-image or react-native-fast-image. Instead of using the uri prop on ImageZoom, you wrap your component as a child.

    <ImageZoom
  ref={ref}
  minScale={minScale}
  maxScale={maxScale}
  scale={scale}
  // ... other props
>
  <Image style={styles.image} source={{ uri }} contentFit="cover" />
</ImageZoom>

  2. Install @likashefqet/react-native-image-zoom

    main

    Install the package using npm or yarn.

    Prerequisites: This library requires react-native-reanimated (v2 or v3) and react-native-gesture-handler (v2). Ensure these are installed and configured in your project first.

    Android Note: If using this component inside a Modal on Android, you must wrap your components with gestureHandlerRootHOC to ensure gestures are detected correctly.

    npm install @likashefqet/react-native-image-zoom

# or

yarn add @likashefqet/react-native-image-zoom

  4. Basic usage of ImageZoom

    main

    To implement a simple zoomable image, import ImageZoom and provide the uri prop. By default, the component handles pinch-to-zoom and panning, and will automatically reset/snap back to the initial position when gestures end.

    import { ImageZoom } from '@likashefqet/react-native-image-zoom';

<ImageZoom uri={imageUri} />

  5. Configure ImageZoom props and callbacks

    main

    The ImageZoom component is highly customizable via props and interactive callbacks.

    Key Configuration Props:

    • minScale, maxScale: Control the zoom boundaries.
    • doubleTapScale: Sets the zoom level for double-tap gestures.
    • isPanEnabled, isPinchEnabled: Enable/disable panning or pinching.
    • isSingleTapEnabled, isDoubleTapEnabled: Enable/disable tap gestures.
    • scale: A Reanimated shared value to access/control the current scale.
    • resizeMode: Supports all standard React Native Image props.

    Interactive Callbacks:

    • onInteractionStart, onInteractionEnd
    • onPinchStart, onPinchEnd
    • onPanStart, onPanEnd
    • onSingleTap, onDoubleTap (returns zoomType)
    • onProgrammaticZoom (returns zoomType)
    • onResetAnimationEnd (returns finished: boolean and values: { SCALE: { lastValue: number } })
    <ImageZoom
  ref={ref}
  uri={uri}
  minScale={1}
  maxScale={5}
  doubleTapScale={3}
  isSingleTapEnabled
  isDoubleTapEnabled
  onInteractionStart={() => console.log('start')}
  onDoubleTap={(zoomType) => console.log('double tap', zoomType)}
  onResetAnimationEnd={(finished, values) => {
    console.log('finished:', finished);
    console.log('last scale:', values?.SCALE.lastValue);
  }}
  resizeMode="cover"
/>

  6. ImageZoom Ref Methods

    main

    You can use a ref to access the following methods on the ImageZoom component to control the image programmatically:

    • reset(): Resets the image zoom, restoring it to its initial position and scale level.
    • zoom(x, y, scale): Zooms in the image to a given point (x, y) at a given scale level. If the provided scale level is less than or equal to 1, it calls the reset method instead.
    | Property | Type | Description |
| --- | --- | --- |
| `reset` | Function | Resets the image zoom, restoring it to its initial position and scale level. |
| `zoom` | Function | Zoom in the image to a given point (x, y) at a given scale level. Calls the reset method if the given scale level is less or equal to 1. |

  7. ImageZoom Props Reference

    main

    The ImageZoom component accepts several props to control zoom behavior, gesture enablement, and interaction callbacks. It also inherits all standard React Native Image Props.

    | Property | Type | Default | Description |
| --- | --- | --- | --- |
| `uri` | String | `''` | The image's URI, which can be overridden by the `source` prop. |
| `minScale` | Number | `1` | The minimum scale allowed for zooming. |
| `maxScale` | Number | `5` | The maximum scale allowed for zooming. |
| `doubleTapScale` | Number | `3` | The value of the image scale when a double-tap gesture is detected. |
| `maxPanPointers` | Number | `2` | The maximum number of pointers required to enable panning. |
| `isPanEnabled` | Boolean | `true` | Determines whether panning is enabled within the range of the minimum and maximum pan pointers. |
| `isPinchEnabled` | Boolean | `true` | Determines whether pinching is enabled. |
| `isSingleTapEnabled` | Boolean | `false` | Enables or disables the single tap feature. |
| `isDoubleTapEnabled` | Boolean | `false` | Enables or disables the double tap feature. When enabled, this feature prevents automatic reset of the image zoom to its initial position, allowing continuous zooming. To return to the initial position, double tap again or zoom out to a scale level less than 1. |
| `onInteractionStart` | Function | `undefined` | A callback triggered when the image interaction starts. |
| `onInteractionEnd` | Function | `undefined` | A callback triggered when the image interaction ends. |
| `onPinchStart` | Function | `undefined` | A callback triggered when the image pinching starts. |
| `onPinchEnd` | Function | `undefined` | A callback triggered when the image pinching ends. |
| `onPanStart` | Function | `undefined` | A callback triggered when the image panning starts. |
| `onPanEnd` | Function | `undefined` | A callback triggered when the image panning ends. |
| `onSingleTap` | Function | `undefined` | A callback triggered when a single tap is detected. |
| `onDoubleTap` | Function | `undefined` | A callback triggered when a double tap gesture is detected. |
| `onProgrammaticZoom` | Function | `undefined` | A callback function that is invoked when a programmatic zoom event occurs. |
| `onResetAnimationEnd` | Function | `undefined` | A callback triggered upon the completion of the reset animation. It accepts two parameters: `finished` and `values`. The `finished` parameter evaluates to true if all animation values have successfully completed the reset animation; otherwise, it is false, indicating interruption by another gesture or unforeseen circumstances. The `values` parameter provides additional detailed information for each animation value. |

  8. Configure ImageZoom props

    main

    The ImageZoomProps type defines the configuration for the image zoom component. It extends standard React Native ImageProps (omitting source) and includes ZoomProps for gesture and scale behavior.

    Key properties include:

    • uri: The image's URI (defaults to '').
    • source: Standard React Native ImageSourcePropType (overrides uri).
    • minScale: Minimum scale allowed (default: 1).
    • maxScale: Maximum scale allowed (default: 5).
    • scale: A Reanimated SharedValue<number> that tracks the current scale. Providing this allows you to sync the zoom level with other parts of your UI.
    • doubleTapScale: The scale level reached when a double-tap occurs (default: 3).
    • maxPanPointers: Maximum number of pointers required to enable panning (default: 2).
    • isPanEnabled: Enables/disables panning (default: true).
    • isPinchEnabled: Enables/disables pinching (default: true).
    • isSingleTapEnabled: Enables/disables single tap feature (default: false).
    • isDoubleTapEnabled: Enables/disables double tap feature. When enabled, double-tapping prevents automatic reset to initial position, allowing continuous zooming (default: false).
    <ImageZoom
  uri="https://example.com/image.jpg"
  minScale={1}
  maxScale={4}
  isDoubleTapEnabled={true}
  doubleTapScale={3}
/>

  9. Handle zoom and gesture callbacks

    main

    The component provides several callback props to respond to user interactions and animation states:

    Gesture Callbacks:

    • onInteractionStart / onInteractionEnd: Triggered when any interaction begins or ends.
    • onPinchStart / onPinchEnd: Triggered during pinch gestures. onPinchEnd provides a success boolean.
    • onPanStart / onPanEnd: Triggered during panning. onPanEnd provides a success boolean.
    • onSingleTap: Triggered when a single tap is detected.
    • onDoubleTap: Triggered when a double tap is detected. Receives a ZOOM_TYPE (ZOOM_IN or ZOOM_OUT).
    • onProgrammaticZoom: Triggered when a zoom() call is made via ref. Receives a ZOOM_TYPE.

    Animation Callbacks:

    • onResetAnimationEnd: Triggered when the reset animation completes. Receives finished (boolean) and values (a record of ANIMATION_VALUE states).

  10. Use useZoomableHandle to expose programmatic zoom controls

    main

    The useZoomableHandle hook is used within a custom component to expose a ZoomableRef to a parent component via useImperativeHandle. This allows a parent to programmatically control the zoom state of a component.

    To use it, you must provide:

    • ref: The React ref being attached to the component.
    • reset: A function to reset the zoom state.
    • zoom: A function to perform a programmatic zoom (accepting a ProgrammaticZoomCallback event).
    • getInfo: A function that returns the current zoom information (GetInfoCallback).

    This hook maps these internal functions to the standard ZoomableRef interface: reset(), zoom(event), and getInfo().

    import { useZoomableHandle } from './useZoomableHandle';

// Inside your custom zoomable component:
useZoomableHandle(
  ref,
  reset,
  zoom,
  getInfo
);

  11. Use the useZoomable hook to enable zoomable behavior

    main

    The useZoomable hook is the primary way to enable zoom, pan, and tap gestures on a component. It orchestrates layout calculations and gesture handling, returning the necessary props to apply to a component and its gesture handlers.

    To use it, pass a configuration object of type UseZoomableProps and receive an object containing animatedStyle, gestures, and onZoomableLayout.

    Key Props for useZoomable:

    • minScale / maxScale: Constraints for the zoom level.
    • scale: The current scale.
    • doubleTapScale: The scale factor applied during a double tap.
    • isPanEnabled / isPinchEnabled: Boolean flags to toggle panning and pinching.
    • isSingleTapEnabled / isDoubleTapEnabled: Boolean flags to toggle single and double tap detection.
    • onInteractionStart / onInteractionEnd: Lifecycle callbacks for any interaction.
    • onPinchStart / onPinchEnd: Lifecycle callbacks for pinch gestures.
    • onPanStart / onPanEnd: Lifecycle callbacks for pan gestures.
    • onSingleTap / onDoubleTap: Callbacks triggered by tap gestures.
    • onProgrammaticZoom: Callback for zoom events triggered via code.
    • onResetAnimationEnd: Callback triggered when a reset animation completes.
    • onLayout: Callback for layout changes.
    • ref: A React ref used to allow programmatic control via useZoomableHandle.
    const { animatedStyle, gestures, onZoomableLayout } = useZoomable({
  minScale: 1,
  maxScale: 3,
  scale: 1,
  doubleTapScale: 2,
  maxPanPointers: 2,
  isPanEnabled: true,
  isPinchEnabled: true,
  isSingleTapEnabled: true,
  isDoubleTapEnabled: true,
  // ... other callbacks
  ref: myRef,
});

// Use 'animatedStyle' on your view/image
// Use 'gestures' with your gesture handler component
// Use 'onZoomableLayout' on your container's onLayout prop