@amazon-devices/react-native-reanimated

@amazon-devices/react-native-reanimated provides a more comprehensive, low level abstraction for the Animated library API to be built on top of and hence allow for much greater flexibility especially when it comes to gesture based interactions.

With Reanimated, you can easily create smooth animations and interactions that run on the UI thread.

This is a system-deployed library and is available to KeplerScript apps without a separate installation process. It is deployed as an autolinking library which your app links to at runtime. Compatibility is guaranteed only between the library and the version of KeplerScript for which it is built.

When you upgrade the version of KeplerScript upon which your app is built, it is best practice to also upgrade the versions of the libraries that depend on KeplerScript.

Documentation

Check out our dedicated documentation page for info about this library, API reference and more: https://docs.swmansion.com/react-native-reanimated/.

Installation

1. Add the dependency in package.json file:

   "dependencies": {
        ...
        "@amazon-devices/react-native-reanimated": "^2.0.0"
   }

2. Add @amazon-devices/react-native-reanimated plugin to your babel.config.js

   module.exports = {
     presets: [
       ... // don't add it here :)
     ],
     plugins: [
       ...
       '@amazon-devices/react-native-reanimated/plugin',
     ],
   };

3. Clear Metro bundler cache using npm start -- --reset-cache command.
4. Reinstall package-lock.json file using npm install command.
5. If you'll need more detailed info, you could refer to the installation section of our docs.

Examples

Example of running a simple animation in an infinite loop using withTiming method.

import React from 'react';
import { StyleSheet, View } from 'react-native';
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withTiming,
  withRepeat,
} from '@amazon-devices/react-native-reanimated';

export default function App() {
  const offset = useSharedValue(200);

  const animatedStyles = useAnimatedStyle(() => ({
    transform: [{ translateX: offset.value }],
  }));

  React.useEffect(() => {
    offset.value = withRepeat(
      withTiming(-offset.value, { duration: 1500 }),
      -1,
      true
    );
  }, []);

  return (
    <View style={styles.container}>
      <Animated.View style={[styles.box, animatedStyles]} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    height: '100%',
  },
  box: {
    height: 120,
    width: 120,
    backgroundColor: '#b58df1',
    borderRadius: 20,
  },
});

Example of running an animation with spring effect.

import React from 'react';
import { StyleSheet, View } from 'react-native';
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
  withRepeat,
} from '@amazon-devices/react-native-reanimated';

const initialOffset = 200;

export default function App() {
  const offset = useSharedValue(initialOffset);

  const animatedStyles = useAnimatedStyle(() => ({
    transform: [{ translateX: offset.value }],
  }));

  React.useEffect(() => {
    offset.value = withRepeat(withSpring(-offset.value), -1, true);
  }, []);

  return (
    <View style={styles.container}>
      <Animated.View style={[styles.box, animatedStyles]} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    height: '100%',
  },
  box: {
    height: 120,
    width: 120,
    backgroundColor: '#b58df1',
    borderRadius: 20,
  },
});

APIs

Reanimated library on Kepler provides a TurboModule which adds a support for most of methods listed below.

Animations

| method | description | platform | | ------- | -------------------- | -------------------- | | withTiming | withTiming lets you create an animation based on duration and easing | All | | withSpring | withSpring lets you create spring-based animations | All | | withDecay | withDecay lets you create animations that mimic objects in motion with friction. The animation will start with the provided velocity and slow down over time according to the given deceleration rate until it stops | All | | withSequence | withSequence is an animation modifier that lets you run animations in a sequence | All | | withRepeat | withRepeat is an animation modifier that lets you repeat an animation given number of times or run it indefinitely | All | | withDelay | withDelay is an animation modifier that lets you start an animation with a delay | All |

Core

| method | description | platform | | ------- | -------------------- | -------------------- | | useSharedValue | useSharedValue lets you define shared values in your components | All | | useAnimatedStyle | useAnimatedStyle lets you create a styles object, similar to StyleSheet styles, which can be animated | All | | useAnimatedProps | useAnimatedProps lets you create an animated props object which can be animated using shared values | All | | useAnimatedRef | useAnimatedRef lets you get a reference of a view. Used alongside measure, scrollTo, and useScrollViewOffset functions | All | | useDerivedValue | useDerivedValue lets you create new shared values based on existing ones while keeping them reactive | All | | createAnimatedComponent | createAnimatedComponent lets you create an Animated version of any React Native component. Wrapping a component with createAnimatedComponent allows Reanimated to animate any prop or style associated with that component | All | | cancelAnimation | cancelAnimation lets you cancel a running animation paired to a shared value | All |

Scroll

| method | description | platform | | ------- | -------------------- | -------------------- | | scrollTo | scrollTo provides synchronous scroll on the UI thread to a given offset using an animated ref to a scroll view. This allows performing smooth scrolling without lags | All | | useScrollViewOffset | useScrollViewOffset allows you to create animations based on the offset of a ScrollView. The hook automatically detects if the ScrollView is horizontal or vertical. | All | | useAnimatedScrollHandler | useAnimatedScrollHandler is a convenience hook that returns an event handler reference which can be used with React Native's scrollable components | All |

Device

| method | description | platform | | ------- | -------------------- | -------------------- | | useAnimatedKeyboard | useAnimatedKeyboard allows creating animations based on current keyboard position | All | | useAnimatedSensor | useAnimatedSensor lets you create animations based on data from the device's sensors: accelerometer, gyroscope, graviry, magnetic field and rotation. | iOS and Android | | useReducedMotion | useReducedMotion lets you query the reduced motion system setting. | iOS and Android |

Threading

| method | description | platform | | ------- | -------------------- | -------------------- | | runOnJS | runOnJS runOnJS lets you asynchronously run non-workletized* functions that couldn't otherwise run on the UI thread | All | | runOnUI | runOnUI lets you asynchronously run workletized functions on the UI thread. | All | | createWorkletRuntime | createWorkletRuntime lets you create a new JS runtime which can be used to run worklets possibly on different threads than JS or UI thread | All |

*to workletize - To convert a JavaScript function into a serializable object which can be copied and ran over on UI thread. Functions marked with "worklet"; directive are automatically picked up and workletized by the Reanimated Babel plugin.

Utilities

| method | description | platform | | ------- | -------------------- | -------------------- | | interpolate | interpolate lets you map a value from one range to another using linear interpolation | All | | clamp | clamp lets you limit a value within a specified range | All | | interpolateColor | interpolateColor maps input range to output colors using linear interpolation | All | | getRelativeCoords | getRelativeCoords determines the location on the screen, relative to the given view | All |

Advanced APIs

| method | description | platform | | ------- | -------------------- | -------------------- | | measure | measure lets you synchronously get the dimensions and position of a view on the screen, all on the UI thread | All | | useAnimatedReaction | useAnimatedReaction allows you to respond to changes in a shared value | All | | useFrameCallback | useFrameCallback lets you run a function on every frame update | All | | useEvent | useEvent is low-level hook returning event handler that will be invoked with native events, which should be used in order to create custom event handler hook like useAnimatedGestureHandler or useAnimatedScrollHandler | All | | useHandler | useHandler is low-level hook returning context object and value indicating whether worklet should be rebuilt, which should be used in order to create custom event handler hook like useAnimatedGestureHandler or useAnimatedScrollHandler | All | | dispatchCommand | dispatchCommand allows to dispatch command on a native component synchronously from the UI thread | All | | setNativeProps | setNativeProps lets you imperatively update component properties | All |

Exceptions on Kepler

Reanimated library on Kepler has a few exceptions in terms of API support. This section will go over those exceptions.

• useAnimatedSensor is not supported on Kepler platform.
• useReducedMotion is not supported on Kepler platform. For Kepler, a setting for enabling/disabling reduced motion is not available so far.
• Layout Animations are not implemented on Fabric yet, so they are not supported on Kepler platform.
• SETs (Shared Element Transitions) allows you to smoothly transform a component from one screen into a component on another screen. It's experimental feature, which hasn't had a support on Kepler yet.
• Animations that use withRepeat will stop repeating after fast refresh is used
• Style does not update on the animation after fast refresh is used

Supported react-native-kepler versions

| package version | @amazon-devices/react-native-kepler version | | ------------- | --------------------------------- | | 2.0.x+3.5.4 | 2.0.x+rn0.72.0 |

Credits

This project has been built and is maintained thanks to the support from Shopify, Expo.io and Software Mansion