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 (`<ScrollView />`) and horizontal (`<ScrollView horizontal={true} />`) scroll views.

Reviewed By: javache

Differential Revision: D90831796

Pulled By: philIip

fbshipit-source-id: 31193b45127bbac4b984452e2b56211a46616c8b
This commit is contained in:
Johan Kasperi authored and meta-codesync[bot] committed 2026-01-17 13:28:32 -08:00
1 parent 3f56ac08ba
commit d9ee4bb0aa
11 files changed
+122 -13

No files matched your search

@@ -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
@@ -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(
@@ -88,6 +88,7 @@ export const __INTERNAL_VIEW_CONFIG: PartialViewConfig =
},
pointerEvents: true,
isInvertedVirtualizedList: true,
scrollsChildToFocus: true,
},
}
: {
@@ -69,6 +69,7 @@ export type ScrollViewNativeProps = Readonly<{
scrollPerfTag?: ?string,
scrollToOverflowEnabled?: ?boolean,
scrollsToTop?: ?boolean,
scrollsChildToFocus?: ?boolean,
sendMomentumEvents?: ?boolean,
showsHorizontalScrollIndicator?: ?boolean,
showsVerticalScrollIndicator?: ?boolean,
@@ -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
@@ -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<View> views, int direction, int focusableMode) {
if (mPagingEnabled && !mPagedArrowScrolling) {
@@ -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.
@@ -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);
@@ -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.
+13 -11
View File
@@ -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<<da31eef1ef6a26b328457cff2dcd3160>>
*
* 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
@@ -545,6 +545,14 @@ if (Platform.OS === 'ios') {
return <AndroidScrollBarOptions />;
},
});
examples.push({
title: '<ScrollView> 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 <ScrollsChildToFocusExample />;
},
});
}
exports.examples = examples;
@@ -566,6 +574,42 @@ const AndroidScrollBarOptions = () => {
);
};
const ScrollsChildToFocusExample = () => {
const [scrollsChildToFocus, setScrollsChildToFocus] = useState(true);
return (
<View>
<RNTesterText style={styles.text}>
Focus a TextInput below to see the scroll behavior.
</RNTesterText>
<ScrollView
style={[styles.scrollView, {height: 200}]}
nestedScrollEnabled
scrollsChildToFocus={scrollsChildToFocus}>
<View style={{padding: 10}}>
<TextInput style={styles.textInput} placeholder="TextInput 1 (top)" />
<View style={{height: 100}} />
<TextInput style={styles.textInput} placeholder="TextInput 2" />
<View style={{height: 100}} />
<TextInput style={styles.textInput} placeholder="TextInput 3" />
<View style={{height: 100}} />
<TextInput
style={styles.textInput}
placeholder="TextInput 4 (bottom)"
/>
</View>
</ScrollView>
<Button
label={'scrollsChildToFocus: ' + scrollsChildToFocus.toString()}
onPress={() => setScrollsChildToFocus(!scrollsChildToFocus)}
/>
<RNTesterText>
When false, focusing a TextInput will not automatically scroll it into
view.
</RNTesterText>
</View>
);
};
const HorizontalScrollView = (props: {
direction: 'ltr' | 'rtl',
itemCount?: number,