@dudigital/react-native-zoomable-view v1.1.4

🚩🚩🚩 Attention: Deprecated 🚩🚩🚩

react-native-zoomable-view

A view component for react-native with pinch to zoom, tap to move and double tap to zoom capability. You can zoom everything, from normal images, text and more complex nested views.

We are using this component already in production in two of our projects, but for quality assurance sake, please consider this component beta. We are happy to hear from you about bugs, issues and would also appreciate your pull requests, if you've made improvements or fixed bugs.

Preview

Getting started

• Installation
• Basic Usage
• Props
• Events
• Pan Responder Hooks
• Example
• Expo Snack Example
• Example Repo

Installation

$ npm install @dudigital/react-native-zoomable-view --save

or

$ yarn add @dudigital/react-native-zoomable-view

Basic Usage

This component is based on react-natives View, enhanced by panresponders and other events to make it zoomable. Therefore no platform specific configuration needs to be done.

Just use it as a drop in component instead of a normal view.

Import ReactNativeZoomableView:

import ReactNativeZoomableView from '@dudigital/react-native-zoomable-view/src/ReactNativeZoomableView';

Use the component:

<ReactNativeZoomableView
   maxZoom={1.5}
   minZoom={0.5}
   zoomStep={0.5}
   initialZoom={1}
   bindToBorders={true}
   onZoomAfter={this.logOutZoomState}
   style={{
      padding: 10,
      backgroundColor: 'red',
   }}
>
   <Text>This is the content</Text>
</ReactNativeZoomableView>

Example

Here is a full drop in example you can use in Expo, after installing the package.

import React from 'react';
import { View, Image } from 'react-native';
import ReactNativeZoomableView from '@dudigital/react-native-zoomable-view/src/ReactNativeZoomableView';

export default class App extends React.Component {
  /**
   * Log out an example event after zooming
   *
   * @param event
   * @param gestureState
   * @param zoomableViewEventObject
   */
  logOutZoomState = (event, gestureState, zoomableViewEventObject) => {
    console.log('');
    console.log('');
    console.log('-------------');
    console.log('Event: ', event);
    console.log('GestureState: ', gestureState);
    console.log('ZoomableEventObject: ', zoomableViewEventObject);
    console.log('');
    console.log(`Zoomed from ${zoomableViewEventObject.lastZoomLevel} to  ${zoomableViewEventObject.zoomLevel}`);
  }

  render() {
    return (
      <View style={{ flex: 1 }}>
        <ReactNativeZoomableView
          maxZoom={1.5}
          minZoom={0.5}
          zoomStep={0.5}
          initialZoom={1}
          bindToBorders={true}
          onZoomAfter={this.logOutZoomState}
          style={{
            padding: 10,
            backgroundColor: 'red',
          }}
        >
          <Image style={{ flex: 1, width: null, height: '100%' }}
                 source={require('./image.jpg')}
                 resizeMode="contain" />
        </ReactNativeZoomableView>
      </View>
    );
  }
}

Expo Snack Example

https://snack.expo.io/SkltQtr8Q

Example Repo

https://github.com/DuDigital/react-native-zoomable-view-example

Props

Options

These options can be used to limit and change the zoom behavior.

Callbacks

These events can be used to work with data after specific events.

Events

The following events allow you to control the ZoomableView zoom level & position from your component. (think of control buttons, ...)

You can find an implementation example in the example repo: https://github.com/DuDigital/react-native-zoomable-view-example

Example:

export default function App() {
  // you will need a reference to the ReactNativeZoomableView component
  const zoomableViewRef = createRef<ReactNativeZoomableView>();

  return (
    <View style={styles.container}>
      <View style={styles.zoomWrapper}>
        <ReactNativeZoomableView
          ref={zoomableViewRef}
          bindToBorders={true}
        >
          <Text style={styles.caption}>HelloWorld</Text>
        </ReactNativeZoomableView>
      </View>

      <View style={styles.controlWrapperLeft}>
        {/* Here you see some examples of moveBy */}
        <Button onPress={() => zoomableViewRef.current!.moveBy(-30, 0)} title="⬅️" />
        <Button onPress={() => zoomableViewRef.current!.moveBy(30, 0)} title="➡️" />
        <Button onPress={() => zoomableViewRef.current!.moveBy(0, -30)} title="⬆️" />
        <Button onPress={() => zoomableViewRef.current!.moveBy(0, 30)} title="⬇️" />

        {/* Here you see an example of moveTo */}
        <Button onPress={() => zoomableViewRef.current!.moveTo(300, 200)} title="Move to" />
      </View>

      <View style={styles.controlWrapperRight}>
        {/* Here you see examples of zoomBy */}
        <Button onPress={() => zoomableViewRef.current!.zoomBy(-0.1)} title="-" />
        <Button onPress={() => zoomableViewRef.current!.zoomBy(0.1)} title="+" />

        {/* Here you see an example of zoomTo */}
        <Button onPress={() => zoomableViewRef.current!.zoomTo(1)} title="reset" />
      </View>
    </View>
  );
}

Pan Responder Hooks

Sometimes you need to change deeper level behavior, so we prepared these panresponder hooks for you.

zoomableViewEventObject

The zoomableViewEventObject object is attached to every event and represents the current state of our zoomable view.

   {
      zoomLevel: number,         // current level of zooming (usually a value between minZoom and maxZoom)
      offsetX: number,           // current offset left
      offsetY: number,           // current offset top
      lastZoomLevel: number,     // last zoom level (before we started the movement)
      lastX: number,             // last offset left (before we started the movement)
      lastY: number,             // last offset top (before we started the movement)
      lastMovePinch: boolean,    // information if a movement is going on
      distanceBottom: number,    // view offset from bottom border
      distanceLeft: number,      // view offset from left border
      distanceRight: number,     // view offset from right border
      distanceTop: number,       // view offset from bottom border
      lastMovePinch: boolean,    // boolean, that states if this movement was a pinch movement
      originalHeight: number,    // original height of the outer view
      originalWidth: number,     // original width of the outer view
      captureEvent: boolean,     // should the panresponder be taken away from parent component (used for react-native modals) 
   }

Special configurations

React Native Modal

To make this work with react-native modals, you have to set the captureEvent prop to true. Otherwise the modal will stop the pinch2zoom event and it will not work.

TODO

• Improve documentation
• Add examples for more complex scenarios (react-native-zoomable-view in a swiper)
• TESTS

Contributing

A lot of people are now using react-native-zoomable-view and there are always smaller things to improve and change. Therefore any contributions are more than welcome! <3

Are you looking to help out and improve this project? Either submit Pull requests with awesome changes or reach out to me on Twitter: https://twitter.com/SimonEritsch Helping hands are always appreciated! :)

How to contribute

Just clone the example repository: https://github.com/DuDigital/react-native-zoomable-view-example

Adjust the package in the typescript files in node_modules/@dudigital/react-native-zoomable-view folder, while running npm transpile in that folder as well. (the transpile command will make sure to transpile the typescript code into javascript)

// We definitely need a better process here. If you have any ideas - please open an issue or PR about a solution. ;) // We would really appreciate it