animated-scrollview v1.1.1

animated-scrollview 🛝

A react native scrollview that lets you easily animate its children based on the scrolling position, to achieve classical one-pager animations etc.

Demo

Playground / Expo Snack

https://snack.expo.dev/@maks-io/animated-scrollview-demo

Example Repository

https://github.com/maks-io/animated-scrollview-example-usage

Installation

If you use expo, use:

expo install animated-scrollview

Otherwise, for npm use:

npm i animated-scrollview --save

And for yarn use:

yarn add animated-scrollview

Usage

Use import { AnimatedScrollview } from "animated-scrollview" to access the main component.

Provide a unique key to every child in your AnimatedScrollview, plus provide a config prop to the AnimatedScrollview itself, where you are referencing the individual children - like so for instance:

<AnimatedScrollview
  config={{
    firstChild: {
      fixate: false,
      relativeOffsetFromBottom: 0,
      springConfig: { mass: 2 },
      animation: {
        opacity: { start: 0, end: 1 },
        translateX: { start: 100, end: 0, unit: "%" },
        rotate: { start: 180, end: 0 },
        order: ["translateX", "rotate"],
      },
    },
  }}
>
  <View key="firstChild">
    <Text>My first Child</Text>
  </View>
  <View key="secondChild">
    <Text>My second Child</Text>
  </View>
  <View key="thirdChild">
    <Text>My third Child</Text>
  </View>
</AnimatedScrollview>

In the example above, only the first child would be animated, since there is no config for the second or third child provided. The first child would have an opacity animation starting from 0 (invisible) to 1 (fully visible) plus some transform animations. Note, how the order prop is also provided, to define the order of transformations. This is mandatory. Any transform prop not occurring in the order array will have no effect. More details below.

Configuration Details

Every child that you want to animate needs to have an entry in the config prop of the AnimatedScrollview component.

The following is a list of things you can configure on a per-child basis:

Stacking children / animations (using 'grandchildren')

Often you want to have different animations for different children, sitting on the same "level" along the y-axis. Like in this example (LINK FOLLOWING SOON), where there are 2 different animations happening "in the same row" (the picture is rotated in, etc., while the text is appearing via opacity).

To achieve this you would want to use grandchildren. The animated-scrollview library can animate both, children and the children of children, for accomplishing this.

Example:

<AnimatedScrollview
  config={{
    firstGrandchild: {
      fixate: false,
      relativeOffsetFromBottom: 0,
      springConfig: { mass: 2 },
      animation: {
        translateX: { start: 100, end: 0, unit: "%" },
        rotate: { start: 180, end: 0 },
        order: ["translateX", "rotate"],
      },
    },
    secondGrandchild: {
      fixate: false,
      relativeOffsetFromBottom: 0,
      springConfig: { mass: 2 },
      animation: {
        opacity: { start: 0, end: 1 },
      },
    },
  }}
>
  <View key="firstChild">
    <Text>My first Child</Text>
  </View>
  <View key="secondChild">
    <Text>My second Child</Text>
  </View>
  <View key="thirdChild">
    <View key="firstGrandchild">
      <Text>My first grandchild</Text>
    </View>
    <View key="secondGrandchild">
      <Text>My second grandchild</Text>
    </View>
  </View>
</AnimatedScrollview>

Note that this works only for 2 levels, meaning children and grandchildren.

Open Tasks

• add missing elements in README
• improve TypeScript usage, there are still 2 remaining @ts-ignore annotations

Improvements / Ideas

• support more CSS transform properties, currently only translateX, translateY, scale and rotate are supported
• Allow generic / global config, so that not every child has to define its own config, as now is the case. Rather it should be possible to override configs for individual children, if desired.
• Same goes for the sub prop springConfig. It should be possible to set it globally but also override it for individual cases, to get more flexibility.