@ekosh02/react-native-animated-header-scroll-view

This is a custom React Native component that simplifies the creation of animated scroll views with dynamic headers. It provides smooth and responsive animations based on the scroll position and extends the standard ScrollView without relying on external libraries like reanimated or gesture-handler

demo-ios

Installation

Install using npm:

npm install @ekosh02/react-native-animated-header-scroll-view

Or using yarn:

yarn add @ekosh02/react-native-animated-header-scroll-view

Features

Simplifies the creation of animated headers in React Native applications.
Smooth scaling and translation animations based on scroll position.
Automatically handles header transitions with fade-in and fade-out effects.
No external dependencies like react-native-reanimated or react-native-gesture-handler.

Usage Example

Here's an example of how to use @ekosh02/react-native-animated-header-scroll-view in a React Native project:

import { AnimatedScrollView } from '@ekosh02/react-native-animated-header-scroll-view'
import { Text, View } from 'react-native'

const ExampleScreen = () => {
  return (
    <AnimatedScrollView
      topHeaderComponent={
        <View>
          <Text>Top Header</Text>
        </View>
      }
      scrolledHeaderComponent={
        <View>
          <Text>Scrolled Header</Text>
        </View>
      }
      contentView={
        <View>
          <Text>Animated Content</Text>
        </View>
      }
    >
      <View>
        <Text>Static child content goes here</Text>
      </View>
    </AnimatedScrollView>
  )
}

export default ExampleScreen

Component Props

The AnimatedScrollView component accepts the following props:

Prop	Type	Description
`topHeaderComponent`	`React.ReactNode`	Component displayed as the main header before scrolling.
`scrolledHeaderComponent`	`React.ReactNode`	Component displayed as the header after scrolling past a threshold.
`contentView`	`React.ReactNode`	Content inside the scroll view that will be animated with scaling and translation effects.
`children`	`React.ReactNode`	Regular static content inside the scroll view.
`scaleMin`	`number`	Controls how much the ContentView shrinks during the scroll animation. For example, scaleMin={0.8} means the ContentView shrinks to 80% of its original size while scrolling.
`...props`	`ScrollViewProps`	Any additional props passed to the underlying `ScrollView`.

Component Behavior

The AnimatedScrollView component automatically provides smooth transitions and animations for the header and content:

Behavior	Description
Header Transition	Smooth fade transitions between `topHeaderComponent` and `scrolledHeaderComponent`, triggered by scroll position.
Content Scaling	The `contentView` element scales down and translates upwards when the user scrolls, creating a parallax effect.
Scroll Tracking	Scroll position is dynamically tracked, triggering appropriate animations and header changes.

Important Information

@ekosh02/react-native-animated-header-scroll-view does not manage safe areas automatically, as it does not use react-native-safe-area-context. You'll need to manually handle the top and bottom indents for safe zones using styles or other approaches. In future versions, we plan to integrate automatic safe area handling to simplify layout management.

Image Scaling Issue

Using scaleMin = 0.7 in ContentView may cause empty spaces around the image due to reduced width.

demo-ios-with-scaling-issue

To fix сalculate the initial image width from screen width and scale to avoid gaps:

Get the screen width using Dimensions.get("window").width.
Calculate INITIAL_WIDTH by dividing the screen width by SCALE_AT_MIN.
Apply INITIAL_WIDTH to your image or content in ContentView to ensure it scales correctly.

import { Dimensions } from 'react-native'

const screenWidth = Dimensions.get('window').width
const SCALE_AT_MIN = 0.7
const INITIAL_WIDTH = screenWidth / SCALE_AT_MIN

Contribution Guidelines

We welcome contributions! Here’s how you can help:

Report issues or request features by opening an issue.
Submit pull requests to suggest fixes or enhancements.

Before contributing, please ensure your code follows the project's style and passes all tests.

License

This project is licensed under the ISC License.

Package detail