Skip to content

Conversation

phamxdinhhien
Copy link

@phamxdinhhien phamxdinhhien commented Oct 14, 2025

Fix: Sticky headers appearing prematurely when firstItemOffset is set

Description

Fixes an issue where sticky headers become active before the header item actually reaches the top of the list when firstItemOffset is applied to the RecyclerView.

Problem

When using stickyHeaderIndices with a FlashList that has content insets, padding, or safe area adjustments (represented by firstItemOffset), the sticky header would appear too early—before the actual header item reached the top of the visible area. This created a jarring user experience where the sticky header appeared while the original header was still visible below it.

Root Cause

The position calculations in StickyHeaders.tsx were not consistently handling firstItemOffset:

  1. The binary search for finding the current sticky index was comparing scroll offset against absolute item Y positions without normalizing for firstItemOffset
  2. The next sticky header Y position calculation was adding firstItemOffset, causing it to be double-counted

This resulted in coordinate space misalignment, leading to premature sticky header activation.

Solution

This PR ensures all position comparisons happen in the same coordinate space by:

  1. Normalizing item positions in binary search (line 95):

    • Subtract firstItemOffset from item Y positions when comparing against scroll offset
    • This ensures the comparison accounts for the content inset
  2. Removing double-counting in next sticky calculation (line 109):

    • Remove the addition of firstItemOffset since it's already included in the layout Y position
    • This prevents the next sticky header from being calculated with an incorrect offset

Changes

  • Modified src/recyclerview/components/StickyHeaders.tsx

Testing

  • Tested with FlashList using contentContainerStyle with paddingTop
  • Tested with contentInset on iOS
  • Verified sticky headers now activate precisely when items reach the top
  • Confirmed smooth push/pull animation between consecutive sticky headers

Impact

  • Fixes sticky header timing issues when firstItemOffset > 0
  • No breaking changes—purely a bug fix
  • Improves UX for lists with content insets or safe area adjustments

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant