Skip to content

fix: fix refs handling for custom scrollables#20

Merged
pawicao merged 1 commit into
mainfrom
fix/custom-lists-refs
Apr 6, 2026
Merged

fix: fix refs handling for custom scrollables#20
pawicao merged 1 commit into
mainfrom
fix/custom-lists-refs

Conversation

@pawicao
Copy link
Copy Markdown
Owner

@pawicao pawicao commented Apr 6, 2026

Summary

This PR fixes scroll synchronization in pager-style multi-tab setups when using third-party list wrappers like FlashList and LegendList.

The root issue was that these libraries expose an outer ref that is not the actual native scroll view Reanimated should drive for imperative scroll synchronization. In that scenario, header state could remain visually collapsed while the underlying list offset was still stale, which caused a jump as soon as the user started dragging again after switching tabs.

What changed

  • Added managedRefTarget to createHeaderMotionScrollable() so custom wrappers can explicitly choose whether Header Motion should synchronize against the outer scrollable ref or the injected inner scroll component.
  • Kept the default as 'outer', preserving backward compatibility and existing behavior for built-in FlatList and other current wrappers.
  • Implemented the inner-ref behavior in the simplest way:
    • when managedRefTarget is 'inner', the wrapper keeps the user-provided animatedRef on the outer component
    • useScrollManager() is allowed to fall back to its own internal ref
    • that internally managed ref is then attached to the injected inner scroll component
  • Added ScrollablePresets for common third-party integrations:
    • ScrollablePresets.FlashList
    • ScrollablePresets.AnimatedLegendList
  • Tightened typing so managedRefTarget is only available when contentContainerMode is renderScrollComponent.
  • Cleaned up and validated the typing for ScrollablePresets.

Examples

  • Updated FlashList and LegendList example screens to use ScrollablePresets.
  • Preserved the built-in FlatList behavior unchanged.

Docs

Updated the docs to reflect the new API and recommended usage:

  • ScrollablePresets is now documented as the preferred path for FlashList and LegendList
  • managedRefTarget is documented as a render-scroll-component-only option
  • external ref behavior is now explained correctly for inner-managed integrations
  • custom scrollables, FAQ, default scrollables, API docs, and README were all refreshed to match the new behavior

Verification

  • Updated and fixed unit tests around createHeaderMotionScrollable()
  • Verified FlatList tests still pass
  • Ran typecheck successfully

@pawicao pawicao merged commit 0db8e57 into main Apr 6, 2026
4 checks passed
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