From d9ee4bb0aa55a71fd2328a8b9dfdca56a4a1e75a Mon Sep 17 00:00:00 2001 From: Johan Kasperi Date: Sat, 17 Jan 2026 13:28:32 -0800 Subject: [PATCH] Add `scrollsChildToFocus` prop to ScrollView to control automatic scrolling when a child receives focus (#55143) Summary: This PR adds a new Android-specific boolean property `scrollsChildToFocus` to the ScrollView component. When a focusable element inside a ScrollView receives focus (e.g., a TextInput is tapped), Android's default behavior is to automatically scroll the ScrollView to bring that element into view. While this is often desirable, there are cases where developers need more control over scroll behavior - for example, when implementing custom scroll-to-focus animations, when using virtualized lists that manage their own scroll positions, or when focus changes should not disturb the current scroll position. Setting `scrollsChildToFocus={false}` disables this automatic scrolling behavior, giving developers full control over scroll positioning when focus changes. **Related issues:** - https://github.com/facebook/react-native/issues/33419 - https://github.com/LegendApp/legend-list/issues/377 ## Changelog: [ANDROID] [ADDED] - Add `scrollsChildToFocus` prop to ScrollView to control automatic scrolling when a child receives focus Pull Request resolved: https://github.com/facebook/react-native/pull/55143 Test Plan: 1. Run the RN Tester app on Android 2. Navigate to ScrollView examples 3. Find the new "scrollsChildToFocus" example in the Android-specific section 4. With `scrollsChildToFocus: true` (default): - Tap on a TextInput that is partially visible - Observe that the ScrollView automatically scrolls to bring the TextInput into view 5. Toggle `scrollsChildToFocus` to `false`: - Tap on a TextInput that is partially visible - Observe that the ScrollView does NOT automatically scroll - the focus changes but scroll position remains unchanged This property affects both vertical (``) and horizontal (``) scroll views. Reviewed By: javache Differential Revision: D90831796 Pulled By: philIip fbshipit-source-id: 31193b45127bbac4b984452e2b56211a46616c8b --- .../Components/ScrollView/ScrollView.d.ts | 9 ++++ .../Components/ScrollView/ScrollView.js | 8 ++++ .../ScrollView/ScrollViewNativeComponent.js | 1 + .../ScrollViewNativeComponentType.js | 1 + .../ReactAndroid/api/ReactAndroid.api | 6 +++ .../scroll/ReactHorizontalScrollView.java | 16 ++++++- .../ReactHorizontalScrollViewManager.kt | 5 +++ .../react/views/scroll/ReactScrollView.java | 16 ++++++- .../views/scroll/ReactScrollViewManager.kt | 5 +++ packages/react-native/ReactNativeApi.d.ts | 24 +++++----- .../examples/ScrollView/ScrollViewExample.js | 44 +++++++++++++++++++ 11 files changed, 122 insertions(+), 13 deletions(-) diff --git a/packages/react-native/Libraries/Components/ScrollView/ScrollView.d.ts b/packages/react-native/Libraries/Components/ScrollView/ScrollView.d.ts index b6e538ddc5a..bd9f15396e7 100644 --- a/packages/react-native/Libraries/Components/ScrollView/ScrollView.d.ts +++ b/packages/react-native/Libraries/Components/ScrollView/ScrollView.d.ts @@ -586,6 +586,15 @@ export interface ScrollViewPropsAndroid { * Causes the scrollbars not to turn transparent when they are not in use. The default value is false. */ persistentScrollbar?: boolean | undefined; + + /** + * When false, the ScrollView will not automatically scroll to a focused child when + * the child requests focus. This can be useful when you want to control the scroll + * position programmatically. The default value is true. + * + * @platform android + */ + scrollsChildToFocus?: boolean | undefined; } export interface ScrollViewProps diff --git a/packages/react-native/Libraries/Components/ScrollView/ScrollView.js b/packages/react-native/Libraries/Components/ScrollView/ScrollView.js index 85e304db34a..468814936a0 100644 --- a/packages/react-native/Libraries/Components/ScrollView/ScrollView.js +++ b/packages/react-native/Libraries/Components/ScrollView/ScrollView.js @@ -388,6 +388,14 @@ export type ScrollViewPropsAndroid = Readonly<{ * @platform android */ fadingEdgeLength?: ?number | {start: number, end: number}, + /** + * When false, the ScrollView will not automatically scroll to a focused child when + * the child requests focus. This can be useful when you want to control the scroll + * position programmatically. The default value is true. + * + * @platform android + */ + scrollsChildToFocus?: ?boolean, }>; type StickyHeaderComponentType = component( diff --git a/packages/react-native/Libraries/Components/ScrollView/ScrollViewNativeComponent.js b/packages/react-native/Libraries/Components/ScrollView/ScrollViewNativeComponent.js index 82f9c93baf3..465131b7144 100644 --- a/packages/react-native/Libraries/Components/ScrollView/ScrollViewNativeComponent.js +++ b/packages/react-native/Libraries/Components/ScrollView/ScrollViewNativeComponent.js @@ -88,6 +88,7 @@ export const __INTERNAL_VIEW_CONFIG: PartialViewConfig = }, pointerEvents: true, isInvertedVirtualizedList: true, + scrollsChildToFocus: true, }, } : { diff --git a/packages/react-native/Libraries/Components/ScrollView/ScrollViewNativeComponentType.js b/packages/react-native/Libraries/Components/ScrollView/ScrollViewNativeComponentType.js index e02f988f403..9cd18a3d2ba 100644 --- a/packages/react-native/Libraries/Components/ScrollView/ScrollViewNativeComponentType.js +++ b/packages/react-native/Libraries/Components/ScrollView/ScrollViewNativeComponentType.js @@ -69,6 +69,7 @@ export type ScrollViewNativeProps = Readonly<{ scrollPerfTag?: ?string, scrollToOverflowEnabled?: ?boolean, scrollsToTop?: ?boolean, + scrollsChildToFocus?: ?boolean, sendMomentumEvents?: ?boolean, showsHorizontalScrollIndicator?: ?boolean, showsVerticalScrollIndicator?: ?boolean, diff --git a/packages/react-native/ReactAndroid/api/ReactAndroid.api b/packages/react-native/ReactAndroid/api/ReactAndroid.api index 5471e9055ca..dd53aa589d7 100644 --- a/packages/react-native/ReactAndroid/api/ReactAndroid.api +++ b/packages/react-native/ReactAndroid/api/ReactAndroid.api @@ -5605,6 +5605,7 @@ public class com/facebook/react/views/scroll/ReactHorizontalScrollView : android public fun reactSmoothScrollTo (II)V public fun requestChildFocus (Landroid/view/View;Landroid/view/View;)V protected fun requestChildFocusWithoutScroll (Landroid/view/View;Landroid/view/View;)V + public fun requestChildRectangleOnScreen (Landroid/view/View;Landroid/graphics/Rect;Z)Z protected fun restoreScrollTo (II)V public fun scrollTo (II)V public fun scrollToPreservingMomentum (II)V @@ -5630,6 +5631,7 @@ public class com/facebook/react/views/scroll/ReactHorizontalScrollView : android public fun setScrollEnabled (Z)V public fun setScrollEventThrottle (I)V public fun setScrollPerfTag (Ljava/lang/String;)V + public fun setScrollsChildToFocus (Z)V public fun setSendMomentumEvents (Z)V public fun setSnapInterval (I)V public fun setSnapOffsets (Ljava/util/List;)V @@ -5684,6 +5686,7 @@ public class com/facebook/react/views/scroll/ReactHorizontalScrollViewManager : public final fun setScrollEnabled (Lcom/facebook/react/views/scroll/ReactHorizontalScrollView;Z)V public final fun setScrollEventThrottle (Lcom/facebook/react/views/scroll/ReactHorizontalScrollView;I)V public final fun setScrollPerfTag (Lcom/facebook/react/views/scroll/ReactHorizontalScrollView;Ljava/lang/String;)V + public final fun setScrollsChildToFocus (Lcom/facebook/react/views/scroll/ReactHorizontalScrollView;Z)V public final fun setSendMomentumEvents (Lcom/facebook/react/views/scroll/ReactHorizontalScrollView;Z)V public final fun setShowsHorizontalScrollIndicator (Lcom/facebook/react/views/scroll/ReactHorizontalScrollView;Z)V public final fun setSnapToAlignment (Lcom/facebook/react/views/scroll/ReactHorizontalScrollView;Ljava/lang/String;)V @@ -5746,6 +5749,7 @@ public class com/facebook/react/views/scroll/ReactScrollView : android/widget/Sc public fun reactSmoothScrollTo (II)V public fun requestChildFocus (Landroid/view/View;Landroid/view/View;)V protected fun requestChildFocusWithoutScroll (Landroid/view/View;Landroid/view/View;)V + public fun requestChildRectangleOnScreen (Landroid/view/View;Landroid/graphics/Rect;Z)Z public fun scrollTo (II)V public fun scrollToPreservingMomentum (II)V public fun setBackgroundColor (I)V @@ -5773,6 +5777,7 @@ public class com/facebook/react/views/scroll/ReactScrollView : android/widget/Sc public fun setScrollEnabled (Z)V public fun setScrollEventThrottle (I)V public fun setScrollPerfTag (Ljava/lang/String;)V + public fun setScrollsChildToFocus (Z)V public fun setSendMomentumEvents (Z)V public fun setSnapInterval (I)V public fun setSnapOffsets (Ljava/util/List;)V @@ -5970,6 +5975,7 @@ public class com/facebook/react/views/scroll/ReactScrollViewManager : com/facebo public final fun setScrollEnabled (Lcom/facebook/react/views/scroll/ReactScrollView;Z)V public final fun setScrollEventThrottle (Lcom/facebook/react/views/scroll/ReactScrollView;I)V public final fun setScrollPerfTag (Lcom/facebook/react/views/scroll/ReactScrollView;Ljava/lang/String;)V + public final fun setScrollsChildToFocus (Lcom/facebook/react/views/scroll/ReactScrollView;Z)V public final fun setSendMomentumEvents (Lcom/facebook/react/views/scroll/ReactScrollView;Z)V public final fun setShowsVerticalScrollIndicator (Lcom/facebook/react/views/scroll/ReactScrollView;Z)V public final fun setSnapToAlignment (Lcom/facebook/react/views/scroll/ReactScrollView;Ljava/lang/String;)V diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactHorizontalScrollView.java b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactHorizontalScrollView.java index 072c5c832c0..b616d52bf37 100644 --- a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactHorizontalScrollView.java +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactHorizontalScrollView.java @@ -136,6 +136,7 @@ public class ReactHorizontalScrollView extends HorizontalScrollView private int mFadingEdgeLengthStart = 0; private int mFadingEdgeLengthEnd = 0; private boolean mEmittedOverScrollSinceScrollBegin = false; + private boolean mScrollsChildToFocus = true; public ReactHorizontalScrollView(Context context) { this(context, null); @@ -199,6 +200,7 @@ public class ReactHorizontalScrollView extends HorizontalScrollView mMaintainVisibleContentPositionHelper = null; mFadingEdgeLengthStart = 0; mFadingEdgeLengthEnd = 0; + mScrollsChildToFocus = true; } /* package */ void recycleView() { @@ -324,6 +326,10 @@ public class ReactHorizontalScrollView extends HorizontalScrollView mPagingEnabled = pagingEnabled; } + public void setScrollsChildToFocus(boolean scrollsChildToFocus) { + mScrollsChildToFocus = scrollsChildToFocus; + } + public void setDecelerationRate(float decelerationRate) { getReactScrollViewScrollState().setDecelerationRate(decelerationRate); @@ -545,7 +551,7 @@ public class ReactHorizontalScrollView extends HorizontalScrollView */ @Override public void requestChildFocus(View child, View focused) { - if (focused != null && !mPagingEnabled) { + if (focused != null && !mPagingEnabled && mScrollsChildToFocus) { scrollToChild(focused); } requestChildFocusWithoutScroll(child, focused); @@ -560,6 +566,14 @@ public class ReactHorizontalScrollView extends HorizontalScrollView super.requestChildFocus(child, focused); } + @Override + public boolean requestChildRectangleOnScreen(View child, Rect rectangle, boolean immediate) { + if (!mScrollsChildToFocus) { + return false; + } + return super.requestChildRectangleOnScreen(child, rectangle, immediate); + } + @Override public void addFocusables(ArrayList views, int direction, int focusableMode) { if (mPagingEnabled && !mPagedArrowScrolling) { diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactHorizontalScrollViewManager.kt b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactHorizontalScrollViewManager.kt index 412500ccbf3..f2bdae139bb 100644 --- a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactHorizontalScrollViewManager.kt +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactHorizontalScrollViewManager.kt @@ -117,6 +117,11 @@ constructor(private val fpsListener: FpsListener? = null) : view.setDisableIntervalMomentum(disableIntervalMomentum) } + @ReactProp(name = "scrollsChildToFocus", defaultBoolean = true) + public fun setScrollsChildToFocus(view: ReactHorizontalScrollView, scrollsChildToFocus: Boolean) { + view.setScrollsChildToFocus(scrollsChildToFocus) + } + @ReactProp(name = "snapToInterval") public fun setSnapToInterval(view: ReactHorizontalScrollView, snapToInterval: Float) { // snapToInterval needs to be exposed as a float because of the Javascript interface. diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactScrollView.java b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactScrollView.java index d1b1ff17ba2..4f70de2cab3 100644 --- a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactScrollView.java +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactScrollView.java @@ -133,6 +133,7 @@ public class ReactScrollView extends ScrollView private int mFadingEdgeLengthStart; private int mFadingEdgeLengthEnd; private boolean mEmittedOverScrollSinceScrollBegin; + private boolean mScrollsChildToFocus = true; public ReactScrollView(Context context) { this(context, null); @@ -196,6 +197,7 @@ public class ReactScrollView extends ScrollView mFadingEdgeLengthStart = 0; mFadingEdgeLengthEnd = 0; mEmittedOverScrollSinceScrollBegin = false; + mScrollsChildToFocus = true; } /* package */ void recycleView() { @@ -298,6 +300,10 @@ public class ReactScrollView extends ScrollView mPagingEnabled = pagingEnabled; } + public void setScrollsChildToFocus(boolean scrollsChildToFocus) { + mScrollsChildToFocus = scrollsChildToFocus; + } + public void setDecelerationRate(float decelerationRate) { getReactScrollViewScrollState().setDecelerationRate(decelerationRate); @@ -507,7 +513,7 @@ public class ReactScrollView extends ScrollView */ @Override public void requestChildFocus(View child, View focused) { - if (focused != null) { + if (focused != null && mScrollsChildToFocus) { scrollToChild(focused); } requestChildFocusWithoutScroll(child, focused); @@ -522,6 +528,14 @@ public class ReactScrollView extends ScrollView super.requestChildFocus(child, focused); } + @Override + public boolean requestChildRectangleOnScreen(View child, Rect rectangle, boolean immediate) { + if (!mScrollsChildToFocus) { + return false; + } + return super.requestChildRectangleOnScreen(child, rectangle, immediate); + } + private int getScrollDelta(View descendent) { descendent.getDrawingRect(mTempRect); offsetDescendantRectToMyCoords(descendent, mTempRect); diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactScrollViewManager.kt b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactScrollViewManager.kt index cc715b64afe..0de168f067d 100644 --- a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactScrollViewManager.kt +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactScrollViewManager.kt @@ -104,6 +104,11 @@ constructor(private val fpsListener: FpsListener? = null) : view.setDisableIntervalMomentum(disableIntervalMomentum) } + @ReactProp(name = "scrollsChildToFocus", defaultBoolean = true) + public fun setScrollsChildToFocus(view: ReactScrollView, scrollsChildToFocus: Boolean) { + view.setScrollsChildToFocus(scrollsChildToFocus) + } + @ReactProp(name = "snapToInterval") public fun setSnapToInterval(view: ReactScrollView, snapToInterval: Float) { // snapToInterval needs to be exposed as a float because of the Javascript interface. diff --git a/packages/react-native/ReactNativeApi.d.ts b/packages/react-native/ReactNativeApi.d.ts index 650c698682a..4a8a22f4583 100644 --- a/packages/react-native/ReactNativeApi.d.ts +++ b/packages/react-native/ReactNativeApi.d.ts @@ -4,7 +4,7 @@ * This source code is licensed under the MIT license found in the * LICENSE file in the root directory of this source tree. * - * @generated SignedSource<<532b4c9c3a1d7ea9cbfce8c8e8ff3d87>> + * @generated SignedSource<> * * This file was generated by scripts/js-api/build-types/index.js. */ @@ -4511,6 +4511,7 @@ declare type ScrollViewNativeProps = Readonly< scrollEventThrottle?: number scrollIndicatorInsets?: EdgeInsetsProp scrollPerfTag?: string + scrollsChildToFocus?: boolean scrollsToTop?: boolean scrollToOverflowEnabled?: boolean sendMomentumEvents?: boolean @@ -4540,6 +4541,7 @@ declare type ScrollViewPropsAndroid = { readonly overScrollMode?: "always" | "auto" | "never" readonly persistentScrollbar?: boolean readonly scrollPerfTag?: string + readonly scrollsChildToFocus?: boolean } declare type ScrollViewPropsIOS = { readonly alwaysBounceHorizontal?: boolean @@ -5994,7 +5996,7 @@ export { AlertOptions, // a0cdac0f AlertType, // 5ab91217 AndroidKeyboardEvent, // e03becc8 - Animated, // 47139b9b + Animated, // ed7eb912 AppConfig, // ebddad4b AppRegistry, // 6cdee1d6 AppState, // 12012be5 @@ -6041,8 +6043,8 @@ export { EventSubscription, // b8d084aa ExtendedExceptionData, // 5a6ccf5a FilterFunction, // bf24c0e3 - FlatList, // a6600e49 - FlatListProps, // de2108a1 + FlatList, // da903f7f + FlatListProps, // 30719d0d FocusEvent, // 529b43eb FontVariant, // 7c7558bb GestureResponderEvent, // b466f6d6 @@ -6179,16 +6181,16 @@ export { ScrollEvent, // 84e5b805 ScrollResponderType, // 8eff013e ScrollToLocationParamsType, // d7ecdad1 - ScrollView, // dcb23e16 + ScrollView, // 29adab85 ScrollViewImperativeMethods, // 92677f19 - ScrollViewProps, // 68051136 - ScrollViewPropsAndroid, // 84e2134b + ScrollViewProps, // 91750f9a + ScrollViewPropsAndroid, // 44210553 ScrollViewPropsIOS, // d83c9733 ScrollViewScrollToOptions, // 3313411e SectionBase, // b376bddc - SectionList, // ab067389 + SectionList, // f27f5afb SectionListData, // 119baf83 - SectionListProps, // e0865379 + SectionListProps, // af193761 SectionListRenderItem, // 1fad0435 SectionListRenderItemInfo, // 745e1992 Separators, // 6a45f7e3 @@ -6253,9 +6255,9 @@ export { ViewStyle, // c2db0e6e VirtualViewMode, // 6be59722 VirtualizedList, // 68c7345e - VirtualizedListProps, // de80b6d7 + VirtualizedListProps, // 555207ac VirtualizedSectionList, // 9fd9cd61 - VirtualizedSectionListProps, // bdbfdf88 + VirtualizedSectionListProps, // 5092b543 WrapperComponentProvider, // 9cf3844c codegenNativeCommands, // 628a7c0a codegenNativeComponent, // a733b8b6 diff --git a/packages/rn-tester/js/examples/ScrollView/ScrollViewExample.js b/packages/rn-tester/js/examples/ScrollView/ScrollViewExample.js index 8f175a5437b..11abb88cde7 100644 --- a/packages/rn-tester/js/examples/ScrollView/ScrollViewExample.js +++ b/packages/rn-tester/js/examples/ScrollView/ScrollViewExample.js @@ -545,6 +545,14 @@ if (Platform.OS === 'ios') { return ; }, }); + examples.push({ + title: ' scrollsChildToFocus\n', + description: + 'When false, the ScrollView will not automatically scroll to a focused child. Useful for controlling scroll position programmatically.', + render(): React.Node { + return ; + }, + }); } exports.examples = examples; @@ -566,6 +574,42 @@ const AndroidScrollBarOptions = () => { ); }; +const ScrollsChildToFocusExample = () => { + const [scrollsChildToFocus, setScrollsChildToFocus] = useState(true); + return ( + + + Focus a TextInput below to see the scroll behavior. + + + + + + + + + + + + +