react-native-animated-header-flat-list

A React Native FlatList component with an animated collapsible header, featuring parallax effects, smooth title transitions, sticky component support, and customizable styles. Built with TypeScript and separate background/content layers in header.

English | 简体中文

Preview

iOS	Android	Web

Features

• Animated collapsible header with parallax effect
• Smooth title transition from header to navigation bar
• Optional sticky component support
• Fully customizable header and title styles
• Separate background and content layers in header
• TypeScript support

Installation

npm install react-native-animated-header-flat-list

Required Peer Dependencies

This library requires the following peer dependencies to be installed in your project:

npm install @react-navigation/native @react-navigation/native-stack @react-navigation/elements react-native-reanimated react-native-safe-area-context

Make sure to follow the installation instructions for each dependency:

• React Navigation
• React Native Reanimated
• React Native Safe Area Context

Additional Setup

For React Native Reanimated, Add react-native-reanimated/plugin plugin to your babel.config.js.

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

CAUTION: react-native-reanimated/plugin has to be listed last.

Usage

import { useNavigation } from '@react-navigation/native';
import { useCallback } from 'react';
import { Image, ImageBackground, StyleSheet, Text, View } from 'react-native';
import { AnimatedHeaderFlatList } from 'react-native-animated-header-flat-list';

export default function HomeScreen() {
  const navigation = useNavigation();
  const data = Array.from({ length: 50 }, (_, index) => ({
    id: `item-${index}`,
    title: `Item ${index + 1}`,
    description: 'Lorem ipsum dolor sit amet',
  }));
  const title = 'Animated Title';
  const backgroundImageUrl =
    'https://images.unsplash.com/photo-1579546929518-9e396f3cc809';
  const avatarUrl = 'https://api.dicebear.com/7.x/avataaars/png?seed=John';

  const HeaderBackground = useCallback(
    () => (
      <ImageBackground
        source={{ uri: backgroundImageUrl }}
        style={styles.headerBackground}
      />
    ),
    [backgroundImageUrl]
  );

  const HeaderContent = useCallback(
    () => (
      <View style={styles.headerContent}>
        <Image source={{ uri: avatarUrl }} style={styles.avatar} />
      </View>
    ),
    [avatarUrl]
  );

  const StickyComponent = useCallback(
    () => <Text style={styles.stickyComponent}>Sticky Item</Text>,
    []
  );

  const renderItem = useCallback(
    ({
      item,
    }: {
      item: { id: string; title: string; description: string };
    }) => (
      <View style={styles.listItem}>
        <Text style={styles.itemTitle}>{item.title}</Text>
        <Text style={styles.itemDescription}>{item.description}</Text>
      </View>
    ),
    []
  );

  return (
    <AnimatedHeaderFlatList
      navigation={navigation}
      title={title}
      headerTitleStyle={styles.headerTitle}
      navigationTitleStyle={styles.navigationTitle}
      HeaderBackground={HeaderBackground}
      HeaderContent={HeaderContent}
      StickyComponent={StickyComponent}
      data={data}
      renderItem={renderItem}
    />
  );
}

const styles = StyleSheet.create({
  headerBackground: {
    backgroundColor: 'white',
    height: 300,
    width: '100%',
  },
  headerContent: {
    height: 300,
    width: '100%',
  },
  avatar: {
    position: 'absolute',
    top: 80,
    left: 10,
    backgroundColor: 'white',
    width: 120,
    height: 120,
    borderRadius: 60,
    borderWidth: 2,
    borderColor: 'white',
  },
  headerTitle: {
    position: 'absolute',
    top: 200,
    left: 10,
    fontSize: 30,
    fontWeight: 'bold',
    color: 'white',
  },
  navigationTitle: {
    fontSize: 18,
    fontWeight: '600',
    color: 'white',
  },
  stickyComponent: {
    backgroundColor: 'white',
    padding: 15,
    borderWidth: 1,
    borderColor: '#EEEEEE',
  },
  listItem: {
    padding: 15,
    borderBottomWidth: 1,
    borderBottomColor: '#EEEEEE',
    backgroundColor: 'white',
  },
  itemTitle: {
    fontSize: 16,
    fontWeight: '600',
  },
  itemDescription: {
    fontSize: 14,
    color: '#666666',
    marginTop: 4,
  },
});

Props

Prop	Type	Required	Description
navigation	any	Yes	React Navigation navigation prop
title	string	Yes	The title text that will animate between header and navigation bar
headerTitleStyle	StyleProp	No	Style object for the title in the header. Supports all Text style props. Position is relative to header container
navigationTitleStyle	StyleProp	No	Style object for the title in the navigation bar. Supports all Text style props except position-related properties
HeaderBackground	React.ComponentType	Yes	Component to be rendered as the header background
HeaderContent	React.ComponentType	No	Component to be rendered on top of the header background. Its opacity will automatically animate based on scroll position
StickyComponent	React.ComponentType	No	Optional component that sticks below the navigation bar
parallax	boolean	No	Enable/disable parallax effect for header background. Defaults to true
navigationBarColor	ColorValue	No	Color of NavigationBar. Its opacity will automatically animate based on scroll position
...FlatListProps	FlatListProps	-	All standard FlatList props are supported

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

---

Made with create-react-native-library