@shopify/flash-list 2.1.0 → 2.2.1

package/src/FlashListProps.ts

@@ -365,4 +365,47 @@ export interface FlashListProps<TItem>
    * Doing set state inside the callback can lead to infinite loops. Make sure FlashList's props are memoized.
    */
   onCommitLayoutEffect?: () => void;
+
+  /**
+   * Callback invoked when the currently displayed sticky header changes.
+   * Receives the current sticky header index and the previous sticky header index.
+   * This is useful for tracking which header is currently stuck at the top while scrolling.
+   * The index refers to the position of the item in your data array that's being used as a sticky header.
+   */
+  onChangeStickyIndex?: (current: number, previous: number) => void;
+
+  stickyHeaderConfig?:
+    | {
+        /**
+         * If true, the sticky headers will use native driver for animations.
+         * @default true
+         */
+        useNativeDriver?: boolean;
+
+        /**
+         * Offset from the top of the list where sticky headers should stick.
+         * This is useful when you have a fixed header or navigation bar at the top of your screen
+         * and want sticky headers to appear below it instead of at the very top.
+         * @default 0
+         */
+        offset?: number;
+
+        /**
+         * Component to render behind sticky headers (e.g., a backdrop or blur effect).
+         * Renders in front of the scroll view content but behind the sticky header itself.
+         * Useful for creating visual separation or effects like backgrounds with blur.
+         */
+        backdropComponent?:
+          | React.ComponentType<any>
+          | React.ReactElement
+          | null
+          | undefined;
+
+        /**
+         * When a sticky header is displayed, the cell associated with it is hidden.
+         * @default false
+         */
+        hideRelatedCell?: boolean;
+      }
+    | undefined;
 }

package/src/native/config/PlatformHelper.android.ts

@@ -1,7 +1,10 @@
+import { isRN083OrAbove } from "./versionCheck";
+
 const PlatformConfig = {
   defaultDrawDistance: 250,
   supportsOffsetCorrection: true,
   trackAverageRenderTimeForOffsetProjection: true,
+  isRN083OrAbove: isRN083OrAbove(),
 };
 
 export { PlatformConfig };

package/src/native/config/PlatformHelper.ios.ts

@@ -1,7 +1,10 @@
+import { isRN083OrAbove } from "./versionCheck";
+
 const PlatformConfig = {
   defaultDrawDistance: 250,
   supportsOffsetCorrection: true,
   trackAverageRenderTimeForOffsetProjection: false,
+  isRN083OrAbove: isRN083OrAbove(),
 };
 
 export { PlatformConfig };

package/src/native/config/PlatformHelper.ts

@@ -2,6 +2,7 @@ const PlatformConfig = {
   defaultDrawDistance: 250,
   supportsOffsetCorrection: false,
   trackAverageRenderTimeForOffsetProjection: false,
+  isRN083OrAbove: true,
 };
 
 export { PlatformConfig };

package/src/native/config/PlatformHelper.web.ts

@@ -2,6 +2,7 @@ const PlatformConfig = {
   defaultDrawDistance: 500,
   supportsOffsetCorrection: false,
   trackAverageRenderTimeForOffsetProjection: false,
+  isRN083OrAbove: true,
 };
 
 export { PlatformConfig };

package/src/native/config/versionCheck.ts

@@ -0,0 +1,6 @@
+import { Platform } from "react-native";
+
+const rnVersion = Platform.constants?.reactNativeVersion;
+
+export const isRN083OrAbove = () =>
+  rnVersion && (rnVersion.major > 0 || rnVersion.minor >= 83);

package/src/recyclerview/RecyclerView.tsx

@@ -84,6 +84,8 @@ const RecyclerViewComponent = <T,>(
     stickyHeaderIndices,
     maintainVisibleContentPosition,
     onCommitLayoutEffect,
+    onChangeStickyIndex,
+    stickyHeaderConfig,
     ...rest
   } = props;
 
@@ -91,6 +93,13 @@ const RecyclerViewComponent = <T,>(
 
   renderTimeTracker.startTracking();
 
+  // Sticky header config
+  const stickyHeaderOffset = stickyHeaderConfig?.offset ?? 0;
+  const stickyHeaderUseNativeDriver =
+    stickyHeaderConfig?.useNativeDriver ?? true;
+  const stickyHeaderHideRelatedCell =
+    stickyHeaderConfig?.hideRelatedCell ?? false;
+
   // Core refs for managing scroll view, internal view, and child container
   const scrollViewRef = useRef<CompatScroller>(null);
   const internalViewRef = useRef<CompatView>(null);
@@ -108,6 +117,7 @@ const RecyclerViewComponent = <T,>(
   // State for managing layout and render updates
   const [_, setLayoutTreeId] = useLayoutState(0);
   const [__, setRenderId] = useState(0);
+  const [currentStickyIndex, setCurrentStickyIndex] = useState(-1);
 
   // Map to store refs for each item in the list
   const refHolder = useMemo(
@@ -388,6 +398,7 @@ const RecyclerViewComponent = <T,>(
     renderFooter,
     renderEmpty,
     CompatScrollView,
+    renderStickyHeaderBackdrop,
   } = useSecondaryProps(props);
 
   if (
@@ -408,15 +419,23 @@ const RecyclerViewComponent = <T,>(
       if (horizontal) {
         throw new Error(ErrorMessages.stickyHeadersNotSupportedForHorizontal);
       }
+
       return (
         <StickyHeaders
           stickyHeaderIndices={stickyHeaderIndices}
+          stickyHeaderOffset={stickyHeaderOffset}
           data={data}
           renderItem={renderItem}
           scrollY={scrollY}
           stickyHeaderRef={stickyHeaderRef}
           recyclerViewManager={recyclerViewManager}
           extraData={extraData}
+          onChangeStickyIndex={(newStickyHeaderIndex) => {
+            if (stickyHeaderHideRelatedCell) {
+              setCurrentStickyIndex(newStickyHeaderIndex);
+            }
+            onChangeStickyIndex?.(newStickyHeaderIndex, currentStickyIndex);
+          }}
         />
       );
     }
@@ -424,11 +443,15 @@ const RecyclerViewComponent = <T,>(
   }, [
     data,
     stickyHeaderIndices,
+    stickyHeaderOffset,
     renderItem,
     scrollY,
     horizontal,
     recyclerViewManager,
     extraData,
+    currentStickyIndex,
+    onChangeStickyIndex,
+    stickyHeaderHideRelatedCell,
   ]);
 
   // Set up scroll event handling with animation support for sticky headers
@@ -436,11 +459,14 @@ const RecyclerViewComponent = <T,>(
     if (stickyHeaders) {
       return Animated.event(
         [{ nativeEvent: { contentOffset: { y: scrollY } } }],
-        { useNativeDriver: true, listener: onScrollHandler }
+        {
+          useNativeDriver: stickyHeaderUseNativeDriver,
+          listener: onScrollHandler,
+        }
       );
     }
     return onScrollHandler;
-  }, [onScrollHandler, scrollY, stickyHeaders]);
+  }, [onScrollHandler, scrollY, stickyHeaders, stickyHeaderUseNativeDriver]);
 
   const shouldMaintainVisibleContentPosition =
     recyclerViewManager.shouldMaintainVisibleContentPosition();
@@ -464,13 +490,14 @@ const RecyclerViewComponent = <T,>(
     return (
       <CompatView
         style={{
+          marginTop: horizontal ? undefined : stickyHeaderOffset,
           height: horizontal ? undefined : 0,
           width: horizontal ? 0 : undefined,
         }}
         ref={firstChildViewRef}
       />
     );
-  }, [horizontal]);
+  }, [horizontal, stickyHeaderOffset]);
 
   const scrollAnchor = useMemo(() => {
     if (shouldMaintainVisibleContentPosition) {
@@ -590,10 +617,15 @@ const RecyclerViewComponent = <T,>(
                 ? recyclerViewManager.getChildContainerDimensions()
                 : undefined
             }
+            currentStickyIndex={currentStickyIndex}
+            hideStickyHeaderRelatedCell={stickyHeaderHideRelatedCell}
           />
           {renderEmpty}
           {renderFooter}
         </CompatScrollView>
+        {stickyHeaderIndices && stickyHeaderIndices.length > 0
+          ? renderStickyHeaderBackdrop
+          : null}
         {stickyHeaders}
       </CompatView>
     </RecyclerViewContextProvider>

package/src/recyclerview/ViewHolder.tsx

@@ -47,6 +47,8 @@ export interface ViewHolderProps<TItem> {
   horizontal?: FlashListProps<TItem>["horizontal"];
   /** Callback when the item's size changes */
   onSizeChanged?: (index: number, size: RVDimension) => void;
+  /** Whether this item should be hidden (likely because it is associated with the active sticky header) */
+  hidden: boolean;
 }
 
 /**
@@ -69,6 +71,7 @@ const ViewHolderInternal = <TItem,>(props: ViewHolderProps<TItem>) => {
     ItemSeparatorComponent,
     trailingItem,
     horizontal,
+    hidden,
   } = props;
 
   useLayoutEffect(() => {
@@ -113,6 +116,7 @@ const ViewHolderInternal = <TItem,>(props: ViewHolderProps<TItem>) => {
     maxWidth: layout.maxWidth,
     left: layout.x,
     top: layout.y,
+    opacity: hidden ? 0 : 1,
   } as const;
 
   // TODO: Fix this type issue
@@ -152,7 +156,8 @@ export const ViewHolder = React.memo(
       prevProps.CellRendererComponent === nextProps.CellRendererComponent &&
       prevProps.ItemSeparatorComponent === nextProps.ItemSeparatorComponent &&
       prevProps.trailingItem === nextProps.trailingItem &&
-      prevProps.horizontal === nextProps.horizontal
+      prevProps.horizontal === nextProps.horizontal &&
+      prevProps.hidden === nextProps.hidden
     );
   }
 );

package/src/recyclerview/ViewHolderCollection.tsx

@@ -50,6 +50,10 @@ export interface ViewHolderCollectionProps<TItem> {
    * For startRenderingFromBottom, we need to adjust the height of the container
    */
   getAdjustmentMargin: () => number;
+  /** Current sticky index */
+  currentStickyIndex: number;
+  /** Whether the cell associated with an active sticky header is hidden */
+  hideStickyHeaderRelatedCell: boolean;
 }
 
 /**
@@ -84,6 +88,8 @@ export const ViewHolderCollection = <TItem,>(
     onCommitEffect,
     horizontal,
     getAdjustmentMargin,
+    currentStickyIndex,
+    hideStickyHeaderRelatedCell,
   } = props;
 
   const [renderId, setRenderId] = React.useState(0);
@@ -168,6 +174,7 @@ export const ViewHolderCollection = <TItem,>(
           const trailingItem = ItemSeparatorComponent
             ? data[index + 1]
             : undefined;
+
           return (
             <ViewHolder
               key={reactKey}
@@ -185,6 +192,9 @@ export const ViewHolderCollection = <TItem,>(
               CellRendererComponent={CellRendererComponent}
               ItemSeparatorComponent={ItemSeparatorComponent}
               horizontal={horizontal}
+              hidden={
+                hideStickyHeaderRelatedCell && currentStickyIndex === index
+              }
             />
           );
         })}

package/src/recyclerview/components/StickyHeaders.tsx

@@ -15,6 +15,7 @@ import React, {
 import { Animated, NativeScrollEvent } from "react-native";
 
 import { FlashListProps } from "../..";
+import { PlatformConfig } from "../../native/config/PlatformHelper";
 import { RecyclerViewManager } from "../RecyclerViewManager";
 import { ViewHolder } from "../ViewHolder";
 
@@ -27,6 +28,10 @@ import { CompatAnimatedView } from "./CompatView";
 export interface StickyHeaderProps<TItem> {
   /** Array of indices that should have sticky headers */
   stickyHeaderIndices: number[];
+  /** Offset from the top where sticky headers should stick (in pixels) */
+  stickyHeaderOffset: number;
+  /** Sticky header change handler */
+  onChangeStickyIndex: (index: number) => void;
   /** The data array being rendered */
   data: ReadonlyArray<TItem>;
   /** Animated value tracking scroll position */
@@ -56,12 +61,14 @@ interface StickyHeaderState {
 
 export const StickyHeaders = <TItem,>({
   stickyHeaderIndices,
+  stickyHeaderOffset,
   renderItem,
   stickyHeaderRef,
   recyclerViewManager,
   scrollY,
   data,
   extraData,
+  onChangeStickyIndex,
 }: StickyHeaderProps<TItem>) => {
   const [stickyHeaderState, setStickyHeaderState] = useState<StickyHeaderState>(
     {
@@ -91,7 +98,7 @@ export const StickyHeaders = <TItem,>({
     // Binary search for current sticky index
     const currentIndexInArray = findCurrentStickyIndex(
       sortedIndices,
-      adjustedScrollOffset,
+      adjustedScrollOffset + stickyHeaderOffset,
       (index) => recyclerViewManager.getLayout(index).y
     );
 
@@ -102,7 +109,8 @@ export const StickyHeaders = <TItem,>({
       newNextStickyIndex = -1;
     }
 
-    // To make sure header offset is 0 in the interpolate compute
+    // Calculate when the next sticky header should start pushing the current one
+    // The next header starts pushing when it reaches the bottom of the current sticky header
     const newNextStickyY =
       newNextStickyIndex === -1
         ? Number.MAX_SAFE_INTEGER
@@ -111,6 +119,7 @@ export const StickyHeaders = <TItem,>({
     const newCurrentStickyHeight =
       recyclerViewManager.tryGetLayout(newStickyIndex)?.height ?? 0;
 
+    // Push should start when the next header reaches the bottom of the current sticky header
     const newPushStartsAt = newNextStickyY - newCurrentStickyHeight;
 
     if (
@@ -119,15 +128,21 @@ export const StickyHeaders = <TItem,>({
     ) {
       setStickyHeaderState({
         currentStickyIndex: newStickyIndex,
-        pushStartsAt: newPushStartsAt,
+        pushStartsAt: newPushStartsAt - stickyHeaderOffset,
       });
     }
+
+    if (newStickyIndex !== currentStickyIndex) {
+      onChangeStickyIndex?.(newStickyIndex);
+    }
   }, [
     legthInvalid,
     recyclerViewManager,
     sortedIndices,
     currentStickyIndex,
     pushStartsAt,
+    onChangeStickyIndex,
+    stickyHeaderOffset,
   ]);
 
   useEffect(() => {
@@ -147,16 +162,32 @@ export const StickyHeaders = <TItem,>({
 
   const refHolder = useRef(new Map()).current;
 
-  const translateY = useMemo(() => {
+  const { translateY, opacity } = useMemo(() => {
     const currentStickyHeight =
       recyclerViewManager.tryGetLayout(currentStickyIndex)?.height ?? 0;
 
-    return scrollY.interpolate({
-      inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
-      outputRange: [0, -currentStickyHeight],
-      extrapolate: "clamp",
-    });
-  }, [recyclerViewManager, currentStickyIndex, scrollY, pushStartsAt]);
+    return {
+      translateY: scrollY.interpolate({
+        inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
+        outputRange: [0, -currentStickyHeight],
+        extrapolate: "clamp",
+      }),
+      opacity:
+        stickyHeaderOffset > 0
+          ? scrollY.interpolate({
+              inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
+              outputRange: [1, 0],
+              extrapolate: "clamp",
+            })
+          : undefined,
+    };
+  }, [
+    recyclerViewManager,
+    currentStickyIndex,
+    scrollY,
+    pushStartsAt,
+    stickyHeaderOffset,
+  ]);
 
   // Memoize header content
   const headerContent = useMemo(() => {
@@ -164,11 +195,12 @@ export const StickyHeaders = <TItem,>({
       <CompatAnimatedView
         style={{
           position: "absolute",
-          top: 0,
+          top: stickyHeaderOffset,
           left: 0,
           right: 0,
-          zIndex: 1,
+          zIndex: 2,
           transform: [{ translateY }],
+          opacity,
         }}
       >
         {currentStickyIndex !== -1 && currentStickyIndex < data.length ? (
@@ -181,11 +213,25 @@ export const StickyHeaders = <TItem,>({
             extraData={extraData}
             trailingItem={null}
             target="StickyHeader"
+            hidden={false}
           />
         ) : null}
       </CompatAnimatedView>
     );
-  }, [translateY, currentStickyIndex, data, renderItem, refHolder, extraData]);
+  }, [
+    translateY,
+    opacity,
+    currentStickyIndex,
+    data,
+    renderItem,
+    refHolder,
+    extraData,
+    stickyHeaderOffset,
+  ]);
+
+  if (PlatformConfig.isRN083OrAbove && currentStickyIndex === -1) {
+    return null;
+  }
 
   return headerContent;
 };

package/src/recyclerview/hooks/useSecondaryProps.tsx

@@ -20,6 +20,7 @@ import { CompatAnimatedScroller } from "../components/CompatScroller";
  *   - renderHeader: The header component renderer
  *   - renderFooter: The footer component renderer
  *   - renderEmpty: The empty state component renderer
+ *   - renderStickyHeaderBackdrop: The sticky header backdrop component renderer
  *   - CompatScrollView: The animated scroll component
  */
 export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
@@ -35,6 +36,7 @@ export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
     onRefresh,
     data,
     refreshControl: customRefreshControl,
+    stickyHeaderConfig,
   } = props;
 
   /**
@@ -94,6 +96,26 @@ export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
     return getValidComponent(ListEmptyComponent);
   }, [ListEmptyComponent, data]);
 
+  /**
+   * Creates the sticky header backdrop component.
+   */
+  const renderStickyHeaderBackdrop = useMemo(() => {
+    if (!stickyHeaderConfig?.backdropComponent) {
+      return null;
+    }
+    return (
+      <CompatView
+        style={{
+          position: "absolute",
+          inset: 0,
+          pointerEvents: "none",
+        }}
+      >
+        {getValidComponent(stickyHeaderConfig?.backdropComponent)}
+      </CompatView>
+    );
+  }, [stickyHeaderConfig?.backdropComponent]);
+
   /**
    * Creates an animated scroll component based on the provided renderScrollComponent.
    * If no custom component is provided, uses the default CompatAnimatedScroller.
@@ -120,5 +142,6 @@ export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
     renderFooter,
     renderEmpty,
     CompatScrollView,
+    renderStickyHeaderBackdrop,
   };
 }