react-native-fluid-gestures v0.1.1

Documentation

Declarative animations for React Native and React Native Web.

NOTE: This is a pre-release and should not be used in production.

Installation

Installing react-native-fluid-transitions is simple, both in React Native Web and in React Native.

React Native Web

yarn add react-native-fluid-animations
yarn add react-native-fluid-transitions

React Native

yarn add react-native-reanimated
yarn add react-native-fluid-animations
yarn add react-native-fluid-transitions

Remember to run react-native-link or cd ios && pod install (depending on your version of React Native) after installing the dependencies.

Example

Getting your first transitions set up is really easy:

import React, { useState } from "react";
import { StyleSheet } from "react-native";
import Fluid from "react-native-fluid-transitions";

const styles = StyleSheet.create({
  active: { width: 100, height: 100, backgroundColor: "aqua" },
  inactive: { width: 50, height: 50, backgroundColor: "gold" },
});

const MyComponent = () => {
  const [active, setActive] = useState(false);
  const toggle = () => setActive(a => !a);

  return (
    <Fluid.View
      style={active ? styles.active : styles.inactive}
      onPress={toggle}
    />
  );
};

Try using this component in your app and tap the box. The component should automatically interpolate between the two styles - including using predefined animations that should work for the different style properties.

API

API reference for Fluid.* components:

• Fluid.View
• Fluid.Image
• Fluid.Text
• Fluid.ScrollView

Fluid.*

Fluid.* components are the basic building blocks of react-native-fluid-transitions. They all implement the same properties as their corresponding React Native components.

Properties

Events

Configuration and States

If you want more control over how animations are played, you can build your own animation definitions using the configuration and state and properties of a Fluid Component.

A simple example illustrates how states and configuration can be used to build transitions:

import React from "react";
import { StyleSheet } from "react-native";
import Fluid, {
  useFluidState,
  useFluidConfig,
} from "react-native-fluid-transitions";

const styles = StyleSheet.create({
  active: { width: 100, height: 100, backgroundColor: "aqua" },
  inactive: { width: 50, height: 50, backgroundColor: "gold" },
});

const MyComponent = () => {
  const [activeState, setActiveState] = useFluidState(false);
  const toggle = () => setActiveState(s => !s);

  const config = useFluidConfig(WhenState(activeState, styles.active));

  return (
    <Fluid.View
      onPress={toggle}
      config={config}
      states={activeState}
      style={styles.inactive}
    />
  );
};

States

A fluid state works as a regular React Native state, and can be created with the hook useFluidState. It returns a state variable and a function for updating the state. This object can be passed along to the Fluid.View through the state property.

const [activeState, setActiveState] = useFluidState(false);
const toggle = () => setActiveState(a => !a);

The example shows how to create and update a state with a simple toggle function.

Configuration

A configuration object consists of the following types:

When

The when configuration field can contain different types of configuration. The when configuration field is created using the WhenState function. This function has several different overloads:

Creates a new when configuration element that applies the provided style when the state is active:

function WhenState(state, style, options?)

Creates a new when configuration element that applies an interpolation when the state is active:

function WhenState(state, interpolation, options?)

Creates a new when configuration element that applies an interpolation returned by the factory function when the state is active:

function WhenState(<a href="#States">state</a>, whenFactory, options?)

Interpolation

An interpolation element consists of the following fields:

Note that the styleKey uses dot-notation, so to build an interpolation for the scale transform you would write "transform.scale".

Options

The object element has a set of optional fields that can be set:

Animation

An animation type is a description of the animation function to run a given animation and can be of two types, spring or timing. An animation type consists of the following fields:

Timing Animation

Spring Animation

onEnter / onExit

If you want an interpolation to run when a state change occurs, you can add OnEnter or OnExit configuration elements to your Fluid.View. The onEnter / onExit element can be created with the OnEnterState / OnExitState functions:

Creates a new onEnter / onExit element describing the interpolation that should be run when the state changes to / from active.

function (state, interpolation, options?)

Where the parameters state, interpolation and options shares the same types as the When element.

This example will add an interpolation that changes the backgroundColor of the View from pink to gold when the myState changes to an active state:

const config = useFluidConfig(
  OnEnterState(myState, {
    styleKey: "backgroundColor",
    inputRange: [0, 1],
    outputRange: ["pink", "gold"],
  }),
);

Child Animation

When animations are played in the context of a parent Fluid.View, you can control how these animations should be played by changing the child configuration. There are three different types of child configuration available:

Sequential();

Paralell();

Staggered(staggerMs? | staggerFunction?, direction)

Value Interpolations

One of the more advanced techniques when building animations and transitions in React Native is when you need your interpolation to depend on a gesture value or a scrolliew position. In react-native-fluid-transitions this is already taken care of for you.

Given a view tree that contains a header and a scroll view:

const label = Label("myScrollView");
return (
  <Fluid.View>
      
    <Fluid.View config={config} staticStyle={styles.header} />
      
    <Fluid.ScrollView label={label}>
                 {children}
        
    </Fluid.ScrollView>
  </Fluid.View>
);

You can add interpolations to the header component's configuration using the scroll position from the scroll view:

const value = InterpolationValue(label, Fluid.ScrollView.ScrollY);
const config = useFluidConfig(
  Interpolation(value, {
    inputRange: [0, 10],
    outputRange: [1, 0.99],
    styleKey: "transform.scale",
  });

A Fluid.ScrollView exposes two values, ScrollY and ScrollX.

Examples

Getting started developing with the examples:

To set up and install:

yarn bootstrap

Start watchers:

yarn dev

Run on iOS / Android:

yarn run-android yarn run-ios