React Native is undergoing an outstanding transformation in the way gestures and animations are conceived. Thanks to the excellent work driven by Krzysztof Magiera, with react-native-gesture-handler and more recently with react-native-reanimated, we are one step closer to achieve the same delightful experiences as we’d have in native mobile apps.

Since a picture is worth a thousand words, take a look at the below GIF:

In case you haven’t noticed, I’ve intentionally blocked the JS thread and everything runs smoothly, even the snapping animation after the finger release. Say whaaat?

Your mileage may vary with Animations in React Native, but the experts will agree that I’ve either cheated or hacked the RN profiler, because they know that can’t be achieved with the current built in infrastructure (aka Animated API)…until now.

Note: If you are super impatient, you can check out the source on GitHub.

I still recommend you continue reading though 🙂

React-native-reanimated

Animated library has several limitations that become troubling when it comes to gesture based interactions. When dragging a box, even though by using Animated.event we could map gesture state to the position of the box and make this whole interaction run on UI thread with useNativeDriver flag, we still have to call back into JS at the end of the gesture for us to start a “snap” animation. That’s because Animated.spring({}).start() cannot be used in a “declarative” manner

This extract from the README file of the library greatly sums up one important pain point when building gesture based interactions with React Native.

Think about the common collapsible navbar pattern used across different popular apps, such as Twitter or Whatssap. To implement snapping, we had to do a lot of manual work, due to problems like Animated.diffClamp not supporting adding listeners to it and having to resort to hacky solutions that led to performance issues and more often than not, brittle code.

React-native-reanimated is a (backwards compatible) reimplementation of Animated API, whose goal is to provide us with more generic and low level primitive node types, so that patterns such as the one above can be implemented declaratively and run on the UI thread like a sweet piece of cheese cake.

Ok, enough theory. Let’s reveal the secret sauce I’ve put together to implement the fancy collapsible navigation bar you saw on the GIF above.

Hiding navigation bar with diffClamp

The first part of the implementation consists of showing or hiding the navigation bar, depending on the direction and amount of scroll. It’s certainly not a new pattern, since it’s been explained before in other blog posts and code samples. Still, let’s do a quick refresher.

Animated.diffclamp is the method that allows us to represent the desired behaviour. It calculates the difference between the current value and the last and then clamp that value. To better illustrate what it does, let’s throw a table with some numbers. What you see below is the output for diffClamp(0, 20) .

Assuming you got a better understanding, let’s scaffold the UI and hook up the corresponding animated values to make that happen. I’ll be omitting some of the code parts for selectively showing what matters. You’ll be able to check the full source code later on.

Let’s explain what’s going on in the constructor:

this.scrollY is the animated value that will be driven by the ScrollView contentOffset.y . The mapping is performed by using Animated.Event . The native driver is running the animation on the UI thread, so we are not affected by the JS thread being blocked.

is the animated value that will be driven by the ScrollView . The mapping is performed by using . The native driver is running the animation on the UI thread, so we are not affected by the JS thread being blocked. diffClampNode represents the Animated.diffClamp(0, NAV_BAR_HEIGHT) operation explained before.

represents the operation explained before. Since we want to hide the navigation bar when scrolling down and show it when scrolling back up, we define animatedNavBarTranslateY as the transformY style applied to it, by inverting the relationship.

as the style applied to it, by inverting the relationship. We interpolate the opacity of the title, so that the title is visible when the navigation bar is visible and viceversa.

New Concepts

So far so good. We’ve got the barebones of our implementation up and running. Now it’s time to show off some magic. But before that, I’ll kindly introduce some new concepts that react-native-reanimated embraces, so that you can have the big picture.

Clocks

Clocks aim to replace animated objects by providing a more low level abstraction, still behaving as animated values. Animated.Clock nodes are a special type of Animated.Value that can be updated in each frame to the timestamp of the current frame. They are also denoted as side effect nodes, since they are in charge of starting and stopping a process (an animation) that updates the value for some time.

The algorithm that evaluates animated nodes works as follows:

Each frame it analyses first the generated events (e.g. touch stream), because they may update some animated values.

Then, it updates values that corresponds to clock nodes that are “running”.

After that, it recursively and efficiently evaluates nodes that are connected to views (and that have to be updated in the current frame).

Finally, it checks if some “running” clocks exist. If so, it enqueues a callback to be evaluated with the next frame.

Blocks

A block is just an array of nodes, where each node is evaluated in order. It returns the value of the last node.

If those terms sound confusing for now, don’t you worry. I am aware it’s difficult to assimilate them at first, by using just words. We’ll soon refer back to those concepts when getting our hands dirty with more code.

Need to conduct React Native training in your company? Talk to us!

Snapping

It’s time to tackle the 2nd part of the implementation, which is the snapping part.

Detecting the end of scrolling

First, we need to figure out how to detect that we’ve finished scrolling. There are 2 callbacks provided by the ScrollView component that can serve as hooks for that, onScrollEndDrag and onMomentumScrollEnd .

OnMomentumScrollEnd will be called only if we release the finger with certain inertia, whereas onScrollEndDrag will be always called after the end of the gesture. For simplicity, we will focus on leveraging onScrollEndDrag .

Following a similar approach as with the onScroll prop, we can use Animated.Event to map the native event velocity.y to an animated value, that we’ll call scrollEndDragVelocity , and use the native driver.

Android and iOS both differ in the native implementation of the onScrollEndDrag callback, bridging inconsistent values for velocities when the callback is executed on the JS realm. iOS reports a velocity of 0 , whilst Android shows a very low value for velocity, but different than 0 .

To circumvent that, we can initialise scrollEndDragVelocity with a very high numerical value and listen for changes, so we’ll know we’ve ended the scrolling gesture when we get a value different than the default one.

With that in mind, we can tweak our previous animatedNavBarTranslateY definition as follows:

Snap threshold

Next piece of the puzzle is to determine which final position the navigation bar should animate to, after the scroll is over. We’ll set the threshold on the value NAV_BAR_HEIGHT / 2 . The snapping point is then defined as:

1 2 3 4 5 const snapPoint = cond ( lessThan ( diffClampNode , NAV_BAR_HEIGHT / 2 ) , 0 , - NAV_BAR_HEIGHT , ) ;

Running the animation

After that, we have to create a function that will run the animation after scrolling. We’ll use a spring based animation.

Now, let’s take a look at how this.animatedNavBarTranslateY is redefined. If the scrolling is over, neq(this.scrollEndDragVelocity, DRAG_END_INITIAL) will evaluate to true . Hence, the cond node will evaluate runSpring and return its value, which will be assigned to this.animatedNavBarTranslateY .

In other words, this.animatedNavBarTranslateY will be driven by the spring animation and not by the scroll contentOffset.y value at that point.

Remember when we talked about clocks and blocks? Now we’ll see them in practise. Let’s go straight to runSpring return value to see how it works.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 return [ cond ( clockRunning ( clock ) , 0 , [ set ( state . finished , 0 ) , set ( state . velocity , velocity ) , set ( state . position , from ) , set ( config . toValue , toValue ) , startClock ( clock ) , ] ) , spring ( clock , state , config ) , cond ( state . finished , [ set ( scrollEndDragVelocity , DRAG_END_INITIAL ) , stopClock ( clock ) , ] ) , state . position , ] ;

The 1st time we call the function, clockRunning(clock) will evaluate to false because the clock node has not been started, so the 3rd argument of the cond node will be evaluated. Since that argument is a block, we evaluate all the nodes in order (which set up the initial state and configuration of the spring animation) and return the value of the last one, which has the side effect of starting a clock node.

spring(clock, state, config) will calculate the position of the animation for the current frame and update state.position accordingly. The next cond will only evaluate if the animation is done, so that we can reset scrollEndDragVelocity and stop the clock.

Finally, we return state.position to the caller, which ends up assigning that value to this.animatedNavBarTranslateY .

If you recall the last step of the react-native-reanimated algorithm, we have a clock running, so a callback is enqueued to the next frame. That will have the effect of going through the block repeatedly, until the clock is stopped, which will occur after the animation finishes.

I am getting quite into details here, but I am doing that so that you can acquire the mental model that react-native-reanimated uses.

Crossing the last mile

We are getting there, but we are still missing one subtle detail. After the snapping finishes, the next time we scroll again we’ll get some weird behaviour.

That’s why as soon as we interact with the ScrollView by dragging, this.animatedNavBarTranslateY will be driven again by multiply(diffClamp(0, NAV_BAR), -1) , which was unaware of the amount applied by the snapping mechanism. The table below illustrates the 2 different scenarios we can run into.

n order to coordinate the two agents that are able to drive the navigation bar position, we can use a new animated value that will be in charge of compensating the amount applied by snapping. We’ll call it snapOffset .

Let’s redefine diffClampNode to account for this new variable:

1 2 3 4 5 6 7 this . snapOffset = new Value ( 0 ) ; const diffClampNode = diffClamp ( add ( this . scrollY , this . snapOffset ) , 0 , NAV_BAR_HEIGHT , ) ; const inverseDiffClampNode = multiply ( diffClampNode , - 1 ) ;

Once our runSpring function completes the animation, state.finished will evaluate to true . At this point, besides reseting scrollEndDragVelocity animated value, it also needs to apply the right amount to snapOffset , depending on the point we are snapping to.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 return [ cond ( clockRunning ( clock ) , 0 , [ set ( state . finished , 0 ) , set ( state . velocity , velocity ) , set ( state . position , from ) , set ( config . toValue , toValue ) , startClock ( clock ) , ] ) , spring ( clock , state , config ) , cond ( state . finished , [ set ( scrollEndDragVelocity , DRAG_END_INITIAL ) , set ( snapOffset , cond ( eq ( toValue , 0 ) , // SnapOffset acts as an accumulator. // We need to keep track of the previous offsets applied. add ( snapOffset , multiply ( diffClampNode , - 1 ) ) , add ( snapOffset , sub ( NAV_BAR_HEIGHT , diffClampNode ) ) , ) , ) , stopClock ( clock ) , ] ) , state . position , ] ;

And that’s it! We’ve finally got everything right in place. If you wanna check the nodes API in details, you can do it here. Putting all together:

Wrapping up

If you’ve managed to read up until this line, give yourself 10 declarative points!

Because being a declarative citizen is what is all about. We’ve defined all the animation system constraints in the component constructor and send them off to the native thread. No more passes over the bridge were needed.Therefore, we are free to carry out whatever heavy computation on the JS thread, or run an infinite loop (just kidding, don’t do that my dear reader), because we have full guarantees that the animation will run slick.

Last but not least, if you wanna play around with the code, here is the repository on GitHub.

Happy coding!

If you liked this article, please recommend it to others ❤️