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

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

Usage

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 data = Array.from({ length: 50 }, (_, index) => ({
    id: `item-${index}`,
    title: `Item ${index + 1}`,
    description: 'Lorem ipsum dolor sit amet',
  }));
  const title = 'Animated Title';

  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
      title={title}
      headerTitleStyle={styles.headerTitle}
      navigationTitleStyle={styles.navigationTitle}
      HeaderBackground={HeaderBackground}
      HeaderContent={HeaderContent}
      StickyComponent={StickyComponent}
      data={data}
      renderItem={renderItem}
    />
  );
}

const HeaderBackground = () => {
  const backgroundImageUrl =
    'https://images.unsplash.com/photo-1579546929518-9e396f3cc809';

  return (
    <ImageBackground
      source={{ uri: backgroundImageUrl }}
      style={styles.headerBackground}
    />
  );
};

const HeaderContent = () => {
  const avatarUrl = 'https://api.dicebear.com/7.x/avataaars/png?seed=John';

  return (
    <View style={styles.headerContent}>
      <Image source={{ uri: avatarUrl }} style={styles.avatar} />
    </View>
  );
};

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

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 | | --------------------------- | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | 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 | | navigationTitleTranslateX | number | No | Horizontal offset for the navigation title position. Defaults to 0 | | navigationTitleTranslateY | number | No | Vertical offset for the navigation title position. Defaults to 0 | | ...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