Skip to main content

FlatListWithHeaders

Component that extends the FlatList to add support for headers exported from this library.

The implementation of this component relies on the HeaderComponent and LargeHeaderComponent props. The HeaderComponent is rendered above the FlatList and the LargeHeaderComponent is rendered as the ListHeaderComponent of the FlatList. Using these two props will allow for animations/built-in features in this library to work properly.

Props​

This component uses the Animated.FlatList under the hood, which inherits all of the props from the FlatList component.

HeaderComponent​

The component to render above the FlatList. This accepts a function that returns a React Element to display as the header. The function will be called with the following arguments:

  • showNavBar: An animated value that will be 0 when the header's subcomponents should be hidden and 1 when they should be shown. This is useful for animating the header's subcomponents. The Header component uses this value to animate its left, center, and right children.

LargeHeaderComponent​

An optional component to render as the large header for this component. This accepts a function that returns a React Element to display as the large header. The function will be called with the following arguments:

  • scrollY: An animated value that keeps track of the current scroll position of the FlatList. This prop is useful for creating custom animations on the large header. In our example, we use the ScalingView component to scale the large header when the user pulls down on the FlatList (to mimic native iOS behaviour).
  • showNavBar: An animated value that keeps track of whether or not the small header is hidden. This prop is useful if you want to create your own custom animations based on whether or not the small header is hidden.

LargeHeaderSubtitleComponent​

An optional component to render as a subtitle for the large header for this component. This accepts a function that returns a React Element to display as the large header subtitle. The function will be called with the following arguments:

  • scrollY: An animated value that keeps track of the current scroll position of the FlatList. This prop is useful for creating custom animations on the large header. In our example, we use the ScalingView component to scale the large header when the user pulls down on the FlatList (to mimic native iOS behaviour).
  • showNavBar: An animated value that keeps track of whether or not the small header is hidden. This prop is useful if you want to create your own custom animations based on whether or not the small header is hidden.

ignoreLeftSafeArea​

An optional boolean that determines whether or not to ignore the left safe area. Defaults to false. The safe area adjustments are used to make sure that the scroll container does not overlap with the notch/headers on different phones - leave this prop as false if you want to respect those safe areas.

ignoreRightSafeArea​

An optional boolean that determines whether or not to ignore the right safe area. Defaults to false. The safe area adjustments are used to make sure that the scroll container does not overlap with the notch/headers on different phones - leave this prop as false if you want to respect those safe areas.

disableAutoFixScroll​

An optional to disable the auto fix scroll mechanism. This is useful if you want to disable the auto scroll when the large header is partially visible. Defaults to false.

containerStyle​

An optional style object that will be applied to the parent container of the scroll container.

largeHeaderContainerStyle​

An optional style object that will be applied to the large header container.

largeHeaderShown​

An optional animated Shared Value that will be mutated by the library when the large header is shown or hidden. This is useful if you would like to track when the large header is shown or hidden.

onLargeHeaderLayout​

An optional callback that will be called when the large header is laid out. This is useful if you want to access the layout of the large header to calculate the height of the large header.

absoluteHeader​

This property controls whether or not the header component is absolutely positioned. This is useful if you want to render a header component that allows for transparency.

Note: This is only available in version >= 0.9.0.

initialAbsoluteHeaderHeight​

This property is used when absoluteHeader is true. This is the initial height of the absolute header. Since the header's height is computed on its layout event, this is used to set the initial height of the header so that it doesn't jump when it is initially rendered.

Note: This is only available in version >= 0.9.0.

headerFadeInThreshold​

A number between 0 and 1 representing at what point the header should fade in, based on the percentage of the LargeHeader's height. For example, if this is set to 0.5, the header will fade in when the scroll position is at 50% of the LargeHeader's height.

Defaults to 1.

Note: This is only available in version >= 0.10.0.

disableLargeHeaderFadeAnim​

Whether or not the LargeHeaderComponent should fade in and out. Defaults to false.

Note: This is only available in version >= 0.10.0.

onScrollWorklet​

A custom worklet that allows custom tracking scroll container's state (i.e., its scroll contentInset, contentOffset, etc.). Please ensure that this function is a worklet.

Since the library uses the onScroll prop to handle animations internally and reanimated does not currently allow for multiple onScroll handlers, you must use this property to track the state of the scroll container's state.

An example is shown below:

const scrollHandlerWorklet = (evt: NativeScrollEvent) => {
  'worklet';
  console.log('offset: ', evt.contentOffset);
};