Home

Awesome

<img src="http://i.imgur.com/ErA2GQo.gif" width=200 />     <img src="http://i.imgur.com/pH6oB5D.gif" width=200 />     <img src="http://i.imgur.com/J5l2Qvq.gif" width=200 />     <img src="http://i.imgur.com/dWFYZBG.gif" width=200 />

Interactable

react-native-interactable

<br>

NPM Version Build Status NPM Downloads

LOOKING FOR A MAINTAINER

We love this project, but currently we don’t have enough time to work on it. So we are looking for a maintainer. If you have enough time and knowledge and want to become one - please let us know (levv@wix.com)

<br>

Description

<br> This is an experimental implementation of a declarative API for handling fluid user interactions with views at 60 FPS in React Native. Here are some example use-cases for views that users can interact with:

All of these use-cases have views that continuously interact with the user's gestures. These interactions are normally physical in nature, having properties like springiness, friction, elasticity and damping. In order to feel natural on a touch device they need to run at 60 FPS.

Why is this challenging?

The async nature of the React Native bridge incurs an inherent performance penalty. This traditionally prevents JavaScript code from running at high framerates. One of the most noticeable challenges is animations in JavaScript, which aren't guaranteed to run at 60 FPS.

Modern animation libraries for React Native, like Animated, tackle this challenge with a declarative approach. In order to minimize passes over the bridge, animations are only declared in JavaScript but executed by a native driver on the other side - in 60 FPS.

Fluid user interactions take this a step further than animations. Interactions require UI to continuously react to the user's gestures. This library is designed to support complex physical interactions with ease, using a full-fledged physics engine to drive the interaction on the native side.

Why is it named interactable?

First off, we are aware that interactable isn't a real word. The correct form is interactive but this has connotation that isn't necessarily related to physical interactions. Similar to Animated.View, we wanted to have Interactable.View - meaning a view you can interact with. And hey, Unity did it too.

<br>

Installation

Requires RN 0.40 and above.

npm install react-native-interactable --save

react-native link react-native-interactable

Note: instead of linking automatically you can also link manually according to these instructions

node_modules/react-native-interactable/ios/Interactable.xcodeproj

Manually link via Cocoa Pods (iOS)

pod 'Interactable', :path => '../node_modules/react-native-interactable'
<br>

Example

<br><br>The playground project has few use-cases implemented like: swipeable card, drawer, collapsible header and chat heads under the "Basic examples" section. It's simplistic but easy to learn from. <br><br>Under the "Real life example" you'll find more complex demonstrations. They're harder to learn from, but they're cool to watch. More info about the UX inspirations for the demo app.

  npm start
  npm run ios

<br><br>Note: It's recommended to experience it on a real device and not on a simulator. The simulator has poor performance so the framerate isn't like the real thing. <br><br>

Usage

The core of this library is the Interactable.View component, used to wrap views you want to interact with:

import Interactable from 'react-native-interactable';

<Interactable.View
  horizontalOnly={true}
  snapPoints={[{x: 0}, {x: -200}]}
  onSnap={this.onDrawerSnap}>

  // the view that you wrap here will now support interactions

</Interactable.View>
<br>

Interactable.View Props

Click here for the full reference for all props

snapPoints={[{x: 0}, {x: -200}]}

springPoints={[{x: 0, tension: 6000, damping: 0.5, influenceArea: {left: 0}}]}

gravityPoints={[{x: 0, y: 0, strength: 8000, falloff: 40, damping: 0.5}]}

frictionAreas={[{damping: 0.5, influenceArea: {top: 0}}]}

alertAreas={[{id: 'myArea', influenceArea: {top: 0}}]}

horizontalOnly={true}

startOnFront

verticalOnly={true}

boundaries={{left: -100, right: 100, bounce: 0.5}}

onSnap={this.onDrawerSnap}

onSnapStart={this.onDrawerSnapStart}

onStop={this.onStopInteraction}

onDrag={this.onDragEvent}

onAlert={this.onAlertEvent}

dragEnabled={true}

dragWithSpring={{tension: 2000, damping: 0.5}}

dragToss={0.1}

animatedValueX={this._deltaX}

animatedValueY={this._deltaY}

animatedNativeDriver={false}

initialPosition={{x: -140, y: -280}}
<br>

Interactable.View Methods

setVelocity(params) - used to imperatively set the view's velocity in order to move it around
instance.setVelocity({x: 2000});

Takes a single argument, which is a params object containing:

snapTo(params) - used to imperatively cause the view to snap to one of its snap points
instance.snapTo({index: 2});

Takes a single argument, which is a params object containing:

changePosition(params) - used to imperatively set the view's position
instance.changePosition({x: 120, y: 40});

Takes a single argument, which is a params object containing:

<br>
bringToFront() - bring view to front (Android Only)
instance.bringToFront();

Animating other views according to Interactable.View position

This library is integrated with the Animated library in order to support performant animations of other views according to the movement of the Interactable.View.

Consider the following use-cases:

In these use-cases, we have views different from the one the user is interacting with, that animate according to the interactive view's position. Since Animated library uses Animated.Value to animate view properties, we support setting the value of an Animated.Value instance according to position of the interactable view. The Animated.Value will contain the delta between the Interactable.View original center and new center. This can be done separately on the X axis and Y axis.

After setting this up, use Animated to declaratively define interpolations of the Animated.Value to various animatable view properties like opacity, scale, rotation, translateX and translateY:

this._deltaY = new Animated.Value(0);

<Animated.View style={{
  transform: [{
    scale: this._deltaY.interpolate({
      inputRange: [-150, -150, 0, 0],
      outputRange: [0.3, 0.3, 1, 1]
    })
  }]
}}>
  ...
</Animated.View>

<Interactable.View
  verticalOnly={true}
  snapPoints={[{y: 0}, {y: -150}]}
  animatedValueY={this._deltaY}
>
  ...
</Interactable.View>
<br>

Implementation Details

Originally, the iOS implementation relied on UIKit Dynamics - a powerful native animation engine for physical interactions. A physics engine is required in order to make the interaction life-like. Consider the action of tossing a view connected via a spring to a snap point. A simple native spring animation will not be enough to take the initial velocity vector into account.

At some point, UIKit Dynamics was dropped in favor of a home-brewed physics implementation in order to provide more control over the behaviors. This also paved the way for the Android port since there's no parallel to UIKit Dynamics for Android. The home-brewed physics engine was straightforward to port from Objective-C to Java and is now part of this library.

Contributing

If you are interested in the project, have feedback or want to contribute don't hesitate to contact me. I'm particularly interested in ideas on how to expand the declarative API for more use-cases and suggestions on how to improve performance. PRs are always welcome.

License

MIT