https://github.com/fram-x/react-native-fluid
Declarative animations for React Native and React Native Web.
https://github.com/fram-x/react-native-fluid
animations navigation react-native transitions
Last synced: about 1 year ago
JSON representation
Declarative animations for React Native and React Native Web.
- Host: GitHub
- URL: https://github.com/fram-x/react-native-fluid
- Owner: fram-x
- License: mit
- Created: 2019-09-15T09:31:04.000Z (almost 7 years ago)
- Default Branch: develop
- Last Pushed: 2022-12-14T17:44:41.000Z (over 3 years ago)
- Last Synced: 2025-06-03T23:49:50.754Z (about 1 year ago)
- Topics: animations, navigation, react-native, transitions
- Language: TypeScript
- Homepage:
- Size: 3.6 MB
- Stars: 94
- Watchers: 8
- Forks: 6
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 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:
```js
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 (
);
};
```
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**
| Property | Description |
| ------------ | ----------------------------------------------------------------------- |
| style | Style that will generate automatic interpolations when changed |
| initialStyle | Initial style for component. Will be interpolated from on mount |
| staticStyle | Style that will not generate interpolations (use for optimizing styles) |
| config | Configuration object |
| states | State / states |
| animation | Animation |
**Events**
| Event | Description |
| ---------------- | --------------------------------------- |
| onPress | Callback when tapped |
| onPressIn | Callback for touch down |
| onPressOut | Callback for touch up |
| onAnimationBegin | Called when style interpolation starts |
| onAnimationEnd | Called when style interpolation is done |
## 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:
```js
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 (
);
};
```
#### 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.
```js
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:
| Field | Description |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| when | Styles or interpolations that will be used when a given state is active |
| onEnter | Interpolation (animation) that will be played when a given state becomes active |
| onExit | Interpolation (animation) that will be played when a given state becomes inactive |
| animation | Animation definition for all items in configuration |
| childAnimation | Describes how child animations should be ordered |
| interpolation | Describes interpolations that should be on at all times. Typically used for interpolations that are driven by a ScrollView or gesture. |
#### 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:**
```js
function WhenState(state, style, options?)
```
**Creates a new when configuration element that applies an interpolation when the state is active:**
```js
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:**
```js
function WhenState(state, whenFactory, options?)
```
**Interpolation**
An interpolation element consists of the following fields:
| Field | Description | Type |
| ----------------- | --------------------------------------------------------- | -------------------------------------- |
| styleKey/propName | Name of the property or style that should be interpolated | String |
| inputRange | Array with input range values | number[] |
| outputRange | Array with output range values | number[] or string[] |
| extrapolate | Extrapolation | 'clamp', 'extend', 'identity' |
| extrapolateLeft | Left extrapolation | 'clamp', 'extend', 'identity' |
| extrapolateRight | Right extrapolation | 'clamp', 'extend', 'identity' |
| animation | Animation type for interpolation | AnimationType |
> 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:
| Field | Description | Type |
| ------- | ------------------------------------------------------ | ------------------ |
| onBegin | Callback on animation start | Function |
| onEnd | Callback on animation end | Function |
| loop | Number of times to loop animation | number or Infinity |
| flip | Number of times to flip animation | number or Infinity |
| yoyo | Number of times to play the animation with yoyo effect | number or Infinity |
**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**
| Field | Description | Type |
| -------- | --------------------------------------------------- | ----------------- |
| type | Type of animation | 'timing' |
| duration | Duration in number of milliseconds | number |
| delay | Delay before starting the animation in milliseconds | number (optional) |
| easing | Curve to apply to the animation | Easing (optional) |
**Spring Animation**
| Field | Description | Type |
| --------- | --------------------------------- | -------- |
| type | Type of animation | 'spring' |
| mass | Mass of the spring animation | number |
| stiffness | Stiffness of the spring animation | number |
| damping | Damping of the spring animation | number |
### 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.**
```js
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:
```js
const config = useFluidConfig(
OnEnterState(myState, {
styleKey: "backgroundColor",
inputRange: [0, 1],
outputRange: ["pink", "gold"],
}),
);
```
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:
```js
Sequential();
```
```js
Paralell();
```
```js
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:
```js
const label = Label("myScrollView");
return (
{children}
);
```
You can add interpolations to the header component's configuration using the scroll position from the scroll view:
```js
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`