Gathering detailed insights and metrics for @mor-trunglam/trung-lam-react-native-image-zoom
Gathering detailed insights and metrics for @mor-trunglam/trung-lam-react-native-image-zoom
A performant and customizable image zoom component built with Reanimated v2+ and TypeScript. 🌃 🚀
1.0.8
MIT
TypeScript
225.87 kB
Installations
npm install @mor-trunglam/trung-lam-react-native-image-zoomDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS
Min. Node Version
>= 16.0.0
Node Version
18.20.2
NPM Version
10.8.3
Releases
Unable to fetch releases
Languages
2
TypeScript
JavaScript
TypeScript (95.62%)
JavaScript (4.38%)
Developer
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
MIT License
52 Commits
1 Branches
1 Contributors
Updated on Oct 25, 2024
Maintainers
1
Package Meta Information
Latest Version
1.0.8
Package Id
@mor-trunglam/trung-lam-react-native-image-zoom@1.0.8
Unpacked Size
225.87 kB
Size
41.29 kB
File Count
101
NPM Version
10.8.3
Node Version
18.20.2
Published on
Oct 25, 2024
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Peer Dependencies
4
Dev Dependencies
22
@commitlint/config-conventional@evilmartians/lefthook@react-native-community/eslint-config@release-it/conventional-changelog@types/jest@types/react@types/react-nativecommitlintdel-clieslinteslint-config-prettiereslint-plugin-prettierjestpod-installprettierreactreact-nativereact-native-builder-bobreact-native-gesture-handlerreact-native-reanimatedrelease-ittypescript
REACT NATIVE IMAGE ZOOM
A performant and customizable image zoom component
built with Reanimated v2+ and TypeScript. 🌃 🚀
Demo:
What's new
-
Enhanced Pan Gesture Handling: Improved the accuracy and responsiveness of pan gestures, ensuring smoother and more natural interactions when panning images.
-
Refined Single Tap Detection: The single tap gesture functionality has been enhanced to trigger more reliably, providing better consistency and control without interfering with other gestures.
-
Updated Example Integration:
- Added new examples demonstrating how to leverage the scale value for custom animation effects.
- Provided an example showcasing how to integrate the Image Zoom Component with react-native-reanimated-carousel, allowing for animated, zoomable image carousels.
-
TypeScript Support for Animated Props: Expanded TypeScript definitions to include support for animated props, ensuring better type safety and compatibility with Reanimated-based animations.
Features
-
Smooth Zooming Gestures: Ensure smooth and responsive zooming functionality, allowing users to easily zoom in and out of images using intuitive pinch and pan gestures.
-
Reset Zoom and Snap Back: The component automatically resets zoom and snaps back to the initial position when the gesture ends.
-
Double Tap to Zoom: Enable a double tap gesture for users to seamlessly zoom in and out of images. When double tap functionality is enabled, the automatic Reset Zoom and Snap Back feature will be disabled, allowing users to maintain their desired zoom level without automatic resets.
-
Single Tap Functionality: Detect and process single tap gestures to trigger specific actions or functionality as needed within the component
-
Customizable Zoom Settings: Utilize
minScale,maxScale, anddoubleTapScaleprops for precise control over minimum, maximum, and double tap zoom levels, tailoring the zoom behavior to application requirements -
Customizable Functionality: Enable or disable features such as panning (
isPanEnabled), pinching (isPinchEnabled), single tap handling (isSingleTapEnabled), and double tap zoom (isDoubleTapEnabled) based on specific application needs. -
Access Scale Animated Value: Provide a Reanimated shared value for the scale property, allowing you to access and utilize the current zoom scale in your own code.
-
Interactive Callbacks: The component provides interactive callbacks such as
onInteractionStart,onInteractionEnd,onPinchStart,onPinchEnd,onPanStart,onPanEnd,onSingleTap,onDoubleTapandonResetAnimationEndthat allow you to handle image interactions. -
Access Last Values on Reset: The
onResetAnimationEndcallback returns the last zoom and position values when the component resets (zooms out), providing more control and feedback for custom logic. -
Ref Handle: Customize the functionality further by utilizing the exposed
resetandzoommethods. The 'reset' method allows you to programmatically reset the image zoom as a side effect to another user action or event, in addition to the default double tap and pinch functionalities. The 'zoom' method allows you to programmatically zoom in the image to a given point (x, y) at a given scale level. -
Reanimated Compatibility: Compatible with
Reanimated v2&Reanimated v3, providing optimized performance and smoother animations during image manipulations`. -
TypeScript Support: Developed with
TypeScriptto enhance codebase maintainability and ensure type safety, reducing potential errors during development and refactoring processes -
Full React Native Image Props Support: The component supports all React Native Image props, making it easy to integrate with existing code and utilize all the features that React Native Image provides.
-
Zoomable Component: This component makes any child elements zoomable, ensuring they behave like the image zoom component. This is particularly useful when you need to replace the default image component with alternatives like Expo Image (see example) or Fast Image.
Getting Started
To use the ImageZoom component, you first need to install the package via npm or yarn. Run either of the following commands:
1npm install @likashefqet/react-native-image-zoom
1yarn add @likashefqet/react-native-image-zoom
[!CAUTION]
🚨
Please note that this library is compatible with
Reanimated v2&Reanimated v3and usesGestureHandler v2.If you haven't installed Reanimated and Gesture Handler yet, please follow the installation instructions for Reanimated and Gesture Handler.
[!NOTE]
Usage with modals on Android
On Android RNGH does not work by default because modals are not located under React Native Root view in native hierarchy. To fix that, components need to be wrapped with gestureHandlerRootHOC (it's no-op on iOS and web).
Usage
First, import the ImageZoom component from the @likashefqet/react-native-image-zoom library:
1import { ImageZoom } from '@likashefqet/react-native-image-zoom';
To use the ImageZoom component, simply pass the uri prop with the URL of the image you want to zoom:
Basic Example
1<ImageZoom uri={imageUri} />
Customized Example
1<ImageZoom 2 ref={ref} 3 uri={uri} 4 minScale={minScale} 5 maxScale={maxScale} 6 scale={scale} 7 doubleTapScale={3} 8 isSingleTapEnabled 9 isDoubleTapEnabled 10 onInteractionStart={() => { 11 console.log('onInteractionStart'); 12 onZoom(); 13 }} 14 onInteractionEnd={() => console.log('onInteractionEnd')} 15 onPanStart={() => console.log('onPanStart')} 16 onPanEnd={() => console.log('onPanEnd')} 17 onPinchStart={() => console.log('onPinchStart')} 18 onPinchEnd={() => console.log('onPinchEnd')} 19 onSingleTap={() => console.log('onSingleTap')} 20 onDoubleTap={(zoomType) => { 21 console.log('onDoubleTap', zoomType); 22 onZoom(zoomType); 23 }} 24 onProgrammaticZoom={(zoomType) => { 25 console.log('onZoom', zoomType); 26 onZoom(zoomType); 27 }} 28 style={styles.image} 29 onResetAnimationEnd={(finished, values) => { 30 console.log('onResetAnimationEnd', finished); 31 console.log('lastScaleValue:', values?.SCALE.lastValue); 32 onAnimationEnd(finished); 33 }} 34 resizeMode="cover" 35/>
Zoomable with Expo Image Example
1<Zoomable 2 ref={ref} 3 minScale={minScale} 4 maxScale={maxScale} 5 scale={scale} 6 doubleTapScale={3} 7 isSingleTapEnabled 8 isDoubleTapEnabled 9 onInteractionStart={() => { 10 console.log('onInteractionStart'); 11 onZoom(); 12 }} 13 onInteractionEnd={() => console.log('onInteractionEnd')} 14 onPanStart={() => console.log('onPanStart')} 15 onPanEnd={() => console.log('onPanEnd')} 16 onPinchStart={() => console.log('onPinchStart')} 17 onPinchEnd={() => console.log('onPinchEnd')} 18 onSingleTap={() => console.log('onSingleTap')} 19 onDoubleTap={(zoomType) => { 20 console.log('onDoubleTap', zoomType); 21 onZoom(zoomType); 22 }} 23 onProgrammaticZoom={(zoomType) => { 24 console.log('onZoom', zoomType); 25 onZoom(zoomType); 26 }} 27 style={styles.image} 28 onResetAnimationEnd={(finished, values) => { 29 console.log('onResetAnimationEnd', finished); 30 console.log('lastScaleValue:', values?.SCALE.lastValue); 31 onAnimationEnd(finished); 32 }} 33> 34 <Image style={styles.image} source={{ uri }} contentFit="cover" /> 35</Zoomable>
Properties
ImageZoom Props
All React Native Image Props &
| Property | Type | Default | Description |
|---|---|---|---|
| uri | String | '' (empty 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. |
ImageZoom Ref
| 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. |
Changelog
Please refer to the Releases section on the GitHub repository. Each release includes a detailed list of changes made to the library, including bug fixes, new features, and any breaking changes. We recommend reviewing these changes before updating to a new version of the library to ensure a smooth transition.
Troubleshooting
Not working on android?
Author
💻 commits |
Support
For ongoing maintenance and updates, your support is greatly appreciated
If you need further assistance, feel free to reach out to me by email at @likashefi.
License
The library is licensed under the MIT License.
No vulnerabilities found.
No security vulnerabilities found.