[feat] Introduce stickyHeaderConfig (offset, backdrop, native driver, hide cell) and onChangeStickyIndex #1953

alexrass · 2025-10-14T13:48:42Z

What problem does this PR solve?

Sticky headers lacked key capabilities needed in real apps:

Could not offset headers to account for top bars (e.g., nav bars).
No way to render a background/backdrop beneath sticky headers.
Duplicate visuals when the original cell remained visible while its header was sticky.
No callback to know which header is currently sticky.

This PR adds configuration and APIs to control sticky header behavior and appearance, while keeping defaults backward compatible.

Changes

Public API
- Added stickyHeaderConfig with:
  - offset: top offset where headers stick (default 0).
  - backdropComponent: renders behind sticky headers.
  - useNativeDriver: controls animation driver (default true).
  - hideRelatedCell: hides the cell for the active sticky header (default false).
- Added onChangeStickyIndex(current, previous) to track sticky header changes.
Behavior/UX
- Sticky header position now supports a top offset (for in-app headers).
- Optional backdrop is layered above content but behind the sticky header.
- Optionally hide the related cell to avoid duplicate visuals.
- Improved push animation; when offset > 0, header fades as it’s pushed.
Internals
- RecyclerView:
  - Passes sticky header config to StickyHeaders.
  - Tracks currentStickyIndex to drive hideRelatedCell.
  - Applies marginTop spacer to content for offset alignment.
  - Uses configured useNativeDriver for scroll animations.
  - Renders backdrop overlay when configured.
- StickyHeaders:
  - Computes current/next sticky indices respecting offset and content layouts.
  - Adjusts push thresholds by offset; sets absolute top = offset; higher z-index.
  - Emits onChangeStickyIndex on index transitions.
- ViewHolder / ViewHolderCollection:
  - New hidden prop to toggle opacity when hideRelatedCell is enabled.
  - Memoization updated to include hidden.
- useSecondaryProps:
  - New renderStickyHeaderBackdrop helper.
Documentation and Examples
- Docs: Added stickyHeaderConfig and onChangeStickyIndex sections with examples.
- Fixture app: New StickyHeaderExample screen with toggles (enable sticky, offset, background).
- Navigation updated to include the new example.
Tests
- New src/tests/StickyHeaders.test.tsx covering:
  - Sticky index selection with/without offset.
  - Push animation thresholds (including firstItemOffset).
  - Callback behavior across scrolls and edge cases.
  - Rendering position with offset.
Changelog
- Added entries for sticky header offset and backgrounds.

Test Plan

Run unit tests:
- yarn test
- Confirm StickyHeaders.test.tsx passes.
Manual verification in fixture app:
- Launch the RN fixture.
- Open “Sticky Headers”.
- Toggle:
  - Enable Sticky Headers: headers stick at scrolling.
  - Sticky Header Offset: headers stick below the top (e.g., 44).
  - Sticky Header Background: backdrop renders behind headers.
  - Hide cell (set in code via hideRelatedCell: true): original cell hides when its header is sticky.
API validation:
- Provide stickyHeaderConfig in an app using FlashList; verify default behavior remains unchanged when config is omitted.
- Add onChangeStickyIndex and log current/previous indices; scroll through list and confirm correct sequence.

naqvitalha · 2025-10-15T16:28:24Z

src/recyclerview/RecyclerView.tsx

          {renderEmpty}
          {renderFooter}
        </CompatScrollView>
+        {stickyHeaderIndices ? renderStickyHeaderBackground : null}


Let's make it something generic. Atleast the name

naqvitalha · 2025-10-15T16:28:39Z

src/recyclerview/RecyclerView.tsx

          {renderHeader}
          {!isHorizontalRTL && viewToMeasureBoundedSize}
+          {/* Spacer for sticky header offset */}
+          {stickyHeaderIndices && stickyHeaderOffset > 0 && (


Let's handle this using contentContainerStyle padding

naqvitalha · 2025-10-17T20:55:10Z

src/recyclerview/components/StickyHeaders.tsx

+        outputRange: [0, -currentStickyHeight],
+        extrapolate: "clamp",
+      }),
+      opacity: stickyHeaderOffset


Let's put an explicit check > 0

naqvitalha · 2025-10-17T20:55:40Z

src/recyclerview/components/StickyHeaders.tsx

  getY: (index: number) => number
 ): number {
+  // Special case: when at the top of the list, show the first sticky header if it's near the top
+  if (adjustedValue <= 0 && sortedIndices.length > 0) {


Can you explain this a bit more?

naqvitalha · 2025-10-17T20:56:12Z

src/recyclerview/hooks/useSecondaryProps.tsx

+        style={{
+          position: "absolute",
+          inset: 0,
+          zIndex: 1,


The zIndex isn't needed I think

naqvitalha · 2025-10-17T20:58:32Z

src/recyclerview/components/StickyHeaders.tsx

  /** Additional data to trigger re-renders */
  extraData: FlashListProps<TItem>["extraData"];
+  /** Sticky header change handler */
+  onChangeStickyIndex?: (index: number) => void;


This can be a useful prop on FlashList too. onChangeStickyIndex: (current, previous) => void. Let's add it.

naqvitalha · 2025-10-22T15:48:46Z

src/recyclerview/components/StickyHeaders.tsx

    }
  }

+  console.log("RESULT", result);


Missing log statement

naqvitalha · 2025-10-22T15:52:56Z

src/recyclerview/RecyclerView.tsx

          {renderEmpty}
          {renderFooter}
        </CompatScrollView>
+        {stickyHeaderIndices ? renderStickyHeaderBackdrop : null}


Let's check length also, in case it's empty

naqvitalha · 2025-10-22T15:55:28Z

src/recyclerview/RecyclerView.tsx

      <CompatView
        style={{
-          height: horizontal ? undefined : 0,
+          height: horizontal ? undefined : 0 + stickyHeaderOffset,


I'm not sure about this. It can throw off compute. I think we discussed doing this will padding instead. You can also try applying it as marginTop here.

… offset spacer, background layer, and header hiding; update docs/changelog and add StickyHeader example in RN fixture

alexrass changed the title ~~[feat] Add stickyHeaderOffset and StickyHeaderBackgroundComponent~~ [feat] Add stickyHeaderOffset and StickyHeaderBackgroundComponent for sticky headers Oct 14, 2025

alexrass force-pushed the arass/flash-list/sticky-header-offsets branch from 2e4a922 to b52a523 Compare October 14, 2025 13:57

alexrass marked this pull request as ready for review October 14, 2025 14:30

alexrass requested a review from naqvitalha October 14, 2025 14:30

naqvitalha reviewed Oct 15, 2025

View reviewed changes

alexrass force-pushed the arass/flash-list/sticky-header-offsets branch from b52a523 to 1fb193a Compare October 15, 2025 19:29

alexrass changed the title ~~[feat] Add stickyHeaderOffset and StickyHeaderBackgroundComponent for sticky headers~~ [feat] Add sticky header offset and backdrop component for FlashList sticky headers Oct 15, 2025

alexrass force-pushed the arass/flash-list/sticky-header-offsets branch from 1fb193a to 6adb670 Compare October 15, 2025 19:33

alexrass changed the title ~~[feat] Add sticky header offset and backdrop component for FlashList sticky headers~~ [feat] Add stickyHeaderOffset and StickyHeaderBackdropComponent for sticky headers Oct 15, 2025

naqvitalha reviewed Oct 17, 2025

View reviewed changes

alexrass force-pushed the arass/flash-list/sticky-header-offsets branch from 6adb670 to 98e5177 Compare October 21, 2025 18:23

alexrass changed the title ~~[feat] Add stickyHeaderOffset and StickyHeaderBackdropComponent for sticky headers~~ [feat] Add sticky header config (offset, backdrop, hide cell) and onChangeStickyIndex Oct 21, 2025

naqvitalha reviewed Oct 22, 2025

View reviewed changes

alexrass force-pushed the arass/flash-list/sticky-header-offsets branch 2 times, most recently from 3585f42 to 76355de Compare October 22, 2025 19:29

alexrass changed the title ~~[feat] Add sticky header config (offset, backdrop, hide cell) and onChangeStickyIndex~~ [feat] Add stickyHeaderConfig (offset, backdrop, hideRelatedCell) and onChangeStickyIndex Oct 22, 2025

naqvitalha approved these changes Oct 22, 2025

View reviewed changes

Add stickyHeaderOffset and StickyHeaderBackgroundComponent; implement…

3da7a69

… offset spacer, background layer, and header hiding; update docs/changelog and add StickyHeader example in RN fixture

alexrass force-pushed the arass/flash-list/sticky-header-offsets branch from 76355de to 3da7a69 Compare October 22, 2025 20:07

alexrass changed the title ~~[feat] Add stickyHeaderConfig (offset, backdrop, hideRelatedCell) and onChangeStickyIndex~~ [feat] Introduce stickyHeaderConfig (offset, backdrop, native driver, hide cell) and onChangeStickyIndex Oct 22, 2025

alexrass enabled auto-merge (squash) October 22, 2025 20:09

alexrass merged commit 0cf8775 into main Oct 22, 2025
10 checks passed

alexrass deleted the arass/flash-list/sticky-header-offsets branch October 22, 2025 20:33

alexrass mentioned this pull request Oct 23, 2025

Add Sticky Header Offset #1930

Closed

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[feat] Introduce stickyHeaderConfig (offset, backdrop, native driver, hide cell) and onChangeStickyIndex #1953

[feat] Introduce stickyHeaderConfig (offset, backdrop, native driver, hide cell) and onChangeStickyIndex #1953

Uh oh!

alexrass commented Oct 14, 2025 •

edited

Loading

Uh oh!

naqvitalha Oct 15, 2025

Uh oh!

naqvitalha Oct 15, 2025

Uh oh!

naqvitalha Oct 17, 2025

Uh oh!

naqvitalha Oct 17, 2025

Uh oh!

naqvitalha Oct 17, 2025

Uh oh!

naqvitalha Oct 17, 2025

Uh oh!

naqvitalha Oct 22, 2025

Uh oh!

naqvitalha Oct 22, 2025

Uh oh!

naqvitalha Oct 22, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

[feat] Introduce stickyHeaderConfig (offset, backdrop, native driver, hide cell) and onChangeStickyIndex #1953

[feat] Introduce stickyHeaderConfig (offset, backdrop, native driver, hide cell) and onChangeStickyIndex #1953

Uh oh!

Conversation

alexrass commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What problem does this PR solve?

Changes

Test Plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alexrass commented Oct 14, 2025 •

edited

Loading