Move Interceptor on ScrollView, not its content

[m-bert]

Description

#4158 introduced ScrollViewResponderInterceptor, which wraps all ScrollView children in a single logical-responder View. RN's ScrollView.render() resolves stickyHeaderIndices against React.Children.toArray(this.props.children) and wraps the child at each sticky index in ScrollViewStickyHeader, which counter-translates that child against the scroll offset. With the content collapsed into one child, index 0 is the entire content — so everything gets pinned. Indices > 0 were a silent no-op (they pointed past the single child).

To fix this, we now move the wrapper outside of ScrollView and handle keyboard dismissal manually.

Fixes #4328

Test plan

Tested on the following code:

import React from 'react';
import { StyleSheet, Text, View } from 'react-native';
import { FlatList, LegacyFlatList } from 'react-native-gesture-handler';

// Repro for https://github.com/software-mansion/react-native-gesture-handler/issues/4328
// v3 FlatList with stickyHeaderIndices: scroll indicator moves, content doesn't.
// LegacyFlatList behaves correctly.

const items = Array.from({ length: 50 }, (_, i) => ({
  id: i.toString(),
  text: `Text content for ${i}`,
}));

export default function EmptyExample() {
  const renderItem = ({ item }: { item: (typeof items)[0] }) => (
    <Text style={styles.item}>{item.text}</Text>
  );

  return (
    <View style={styles.container}>
      <View style={styles.flex1}>
        <FlatList
          data={items}
          keyExtractor={(item) => item.id}
          contentContainerStyle={styles.contentContainer}
          stickyHeaderHiddenOnScroll={false}
          ListHeaderComponentStyle={styles.headerContainer}
          stickyHeaderIndices={[0]}
          ListHeaderComponent={<Text>FlatList (v3) Header</Text>}
          renderItem={renderItem}
        />
      </View>
      <View style={styles.flex1}>
        <LegacyFlatList
          data={items}
          keyExtractor={(item) => item.id}
          contentContainerStyle={styles.contentContainer}
          stickyHeaderHiddenOnScroll={false}
          ListHeaderComponentStyle={styles.headerContainer}
          stickyHeaderIndices={[0]}
          ListHeaderComponent={<Text>LegacyFlatList Header</Text>}
          renderItem={renderItem}
        />
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  flex1: {
    flex: 1,
  },
  headerContainer: {
    paddingTop: 24,
    paddingBottom: 12,
    backgroundColor: '#f6f6f6',
  },
  contentContainer: {
    paddingHorizontal: 24,
  },
  item: {
    paddingVertical: 4,
  },
});

[Copilot]

Pull request overview

This PR fixes a regression in v3 ScrollView/FlatList sticky header behavior introduced by wrapping all ScrollView children into a single logical responder node, which caused stickyHeaderIndices to pin the entire content (or become a no-op for indices > 0). The fix wraps each child individually while preserving the responder-interception behavior via a shared context provider.

Changes:

• Replace the single “logical responder” wrapper with per-child logical wrappers (interceptScrollViewChildren) so stickyHeaderIndices map to the intended children.
• Split the interceptor into a context provider (ScrollViewResponderProvider) plus per-child wrappers (LogicalResponderChild), and apply this in the v3 ScrollView component.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
packages/react-native-gesture-handler/src/v3/components/ScrollViewResponderInterceptor.tsx	Refactors responder interception into a provider + per-child wrapper and adds interceptScrollViewChildren.
packages/react-native-gesture-handler/src/v3/components/GestureComponents.tsx	Updates v3 ScrollView to use the provider and wrap children individually via interceptScrollViewChildren.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[m-bert]

I don't think React <19 is a concern

[j-piasecki]

You're rendering a new non-flattenable view for each ScrollView child. This will measurably impact performance.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/react-native-gesture-handler/src/v3/components/ScrollViewResponderInterceptor.tsx:181

• onResponderRelease also assumes it always receives an event and will throw if it’s called without one while claimedForKeyboardDismissal is true (same test pattern as onStartShouldSetResponder). Making the event parameter optional and guarding before reading event.target avoids a potential crash in tests and keeps the handler defensive.

  const handleResponderRelease = useCallback((event: GestureResponderEvent) => {
    if (!claimedForKeyboardDismissal.current) {
      return;
    }
    claimedForKeyboardDismissal.current = false;

    const currentlyFocusedInput = TextInput.State.currentlyFocusedInput();
    if (
      currentlyFocusedInput != null &&
      keyboardIsDismissible() &&
      event.target !== currentlyFocusedInput
    ) {
      TextInput.State.blurTextInput(currentlyFocusedInput);
    }
  }, []);

[j-piasecki]

The title seems incorrect after the changes

[j-piasecki]

What about always and never?

[m-bert]

In never RN grabs the touch during capture, before children even see it, so there's no conflict with our marks (press suppression comes from isKeyboardDismissingTap, #4281). Disabling the responder there would only break the dismissal.

In always RN does nothing keyboard-related, so there's nothing to intercept. Only handled has the bubble claim that conflicted with the marks, which is why both the flag and the provider's handlers are gated on it.

[j-piasecki]

Does this work with the scrollview's responder disabled? From what I can see in the implementation almost all references to it are in responder callbacks.

[m-bert]

Yeah, it works — the flag only kills the handled bubble claim and its blur-on-release, which is exactly what the provider reimplements. Everything else that reads keyboardShouldPersistTaps is either the never-only capture path (no-op in handled) or the tap-while-decelerating claim, which sits before the disable check and keeps working.

My Claude instrumented it to be sure: with the flag on, a tap during deceleration still hits isAnimating=true, the ScrollView claims it, keyboard stays open, identical to plain RN ScrollView next to it. never/always don't set the flag, so they're fully stock.

Only known gap: our onResponderTerminate stand-in for _observedScrollSinceBecomingResponder doesn't cover a tap landing in the tiny window right after deceleration ends - stock would skip the blur there, we wouldn't. Couldn't trigger it on purpose though.