react-native-sticky-parallax-header

The useStickyHeaderScrollProps hook is the engine for the parallax and snapping behavior. It is a generic hook that needs to know the type of scroll component it is enhancing (e.g., ScrollView, FlatList<ItemT>, or SectionList<ItemT, SectionT>).

It returns several key properties:

• onScroll, onMomentumScrollEnd, onScrollEndDrag: Event handlers that must be passed to the scroll component to manage the snapping logic.
• scrollValue: A value representing the current scroll position, which can be passed to custom header components (like a HeaderBar or Foreground) to drive parallax animations.
• scrollHeight: The total height of the scrollable content, useful for sizing header containers.
• scrollViewRef: A ref to be attached to the scroll component.

These props are then consumed by the StickyHeader component (or its variants) and the renderHeader/renderTabs functions to synchronize the UI with the scroll position.

To implement a fully custom header (e.g., adding a back button, close button, or custom animations), use the renderHeaderBar prop. This prop accepts a function that returns a component.

To create elements that react to the scroll position (like a title that fades in only when the header is collapsed), you can capture the vertical content offset via the onScroll prop and pass it to your custom header component using a Reanimated shared value.

// 1. Capture scroll value
const scrollValue = useSharedValue(0);
const onScroll = (e) => {
  'worklet';
  scrollValue.value = e.contentOffset.y;
};

// 2. Create custom header using the shared value
const HeaderBar = ({ scrollValue }) => {
  const animatedStyle = useAnimatedStyle(() => ({
    opacity: interpolate(scrollValue.value, [0, 60, 90], [0, 0, 1], Extrapolate.CLAMP)
  }));

  return (
    <View>
      <Animated.View style={animatedStyle}>
        <Text>Custom Title</Text>
      </Animated.View>
    </View>
  );
};

// 3. Pass to TabbedHeaderPager
<TabbedHeaderPager
  onScroll={onScroll}
  renderHeaderBar={() => <HeaderBar scrollValue={scrollValue} />}
  {/* ... other props */}
/>

To implement a custom header layout, you must combine the useStickyHeaderScrollProps hook with either the StickyHeader component (which supports ScrollView, FlatList, or SectionList) or a custom scroll component wrapped in the withStickyHeader Higher-Order Component (HOC).

Implementation Steps:

1. Initialize Scroll Props: Call useStickyHeaderScrollProps and pass the configuration object. This hook provides the necessary props to create the "snap effect" behavior.
2. Pass Props to Scroll Component: Pass the returned props (such as onScroll, onMomentumScrollEnd, and onScrollEndDrag) to your StickyHeader component or your withStickyHeader decorated component.
3. Render Custom UI: Use the renderHeader and renderTabs props on the sticky header component to define your custom header or tabs layout.

Configuration Options for useStickyHeaderScrollProps:

• parallaxHeight: The height of the parallax area.
• snapStartThreshold: The threshold at which snapping begins.
• snapStopThreshold: The threshold at which snapping stops.
• snapToEdge: Boolean to determine if snapping should go to the edge.

const { 
  onMomentumScrollEnd, 
  onScroll, 
  onScrollEndDrag, 
  scrollHeight, 
  scrollValue, 
  scrollViewRef 
} = useStickyHeaderScrollProps<ScrollView>({
  parallaxHeight: PARALLAX_HEIGHT,
  snapStartThreshold: SNAP_START_THRESHOLD,
  snapStopThreshold: SNAP_STOP_THRESHOLD,
  snapToEdge: true,
});

// ...

<StickyHeaderScrollView
  ref={scrollViewRef}
  onScroll={onScroll}
  onMomentumScrollEnd={onMomentumScrollEnd}
  onScrollEndDrag={onScrollEndDrag}
  renderHeader={() => (
    <View pointerEvents="box-none" style={{ height: scrollHeight }}>
      <Foreground scrollValue={scrollValue} />
    </View>
  )}
  renderTabs={() => (
    <View style={styles.tabContainer}>
      <Tabs />
    </View>
  )}
>
  {/* Scroll Content */}
</StickyHeaderScrollView>