feat: add scroll snapping when focusing

Author: RuudBurger

packages/react-native/Libraries/Components/ScrollView/AndroidHorizontalScrollViewNativeComponent.js

@@ -58,6 +58,8 @@ export const __INTERNAL_VIEW_CONFIG: PartialViewConfig = {
     borderLeftColor: {
       process: require('../../StyleSheet/processColor').default,
     },
+    scrollSnapType: true,
+    scrollPadding: true,
     pointerEvents: true,
   },
 };

packages/react-native/Libraries/Components/ScrollView/ScrollView.js

@@ -654,6 +654,8 @@ type ScrollViewBaseProps = $ReadOnly<{
    * This can improve scrolling performance on long lists. The default value is
    * true.
    */
+  scrollSnapType?: ?('mandatory' | 'none'),
+  scrollPadding?: ?number,
   removeClippedSubviews?: ?boolean,
   /**
    * A RefreshControl component, used to provide pull-to-refresh
@@ -789,6 +791,8 @@ class ScrollView extends React.Component<ScrollViewProps, ScrollViewState> {
       );
     }
 
+    this._warnIfScrollSnapConflict();
+
     this._keyboardMetrics = Keyboard.metrics();
     this._additionalScrollOffset = 0;
 
@@ -823,6 +827,8 @@ class ScrollView extends React.Component<ScrollViewProps, ScrollViewState> {
       this._scrollAnimatedValue.setOffset(newContentInsetTop || 0);
     }
 
+    this._warnIfScrollSnapConflict(prevProps);
+
     this._updateAnimatedNodeAttachment();
   }
 
@@ -1018,6 +1024,31 @@ class ScrollView extends React.Component<ScrollViewProps, ScrollViewState> {
       Commands.zoomToRect(component, rect, animated !== false);
     };
 
+  _warnIfScrollSnapConflict(prevProps?: ScrollViewProps) {
+    const hasConflict =
+      this.props.scrollSnapType != null &&
+      (this.props.snapToInterval != null ||
+        this.props.snapToAlignment != null);
+    if (!hasConflict) {
+      return;
+    }
+    // On update, only warn when the conflict is newly introduced.
+    if (
+      prevProps != null &&
+      prevProps.scrollSnapType != null &&
+      (prevProps.snapToInterval != null || prevProps.snapToAlignment != null)
+    ) {
+      return;
+    }
+    console.warn(
+      'ScrollView: `scrollSnapType` should not be used together with ' +
+        '`snapToInterval` or `snapToAlignment`. `scrollSnapType` provides ' +
+        'focus-driven snapping for TV, while `snapToInterval`/' +
+        '`snapToAlignment` provide momentum-based snapping. Using both ' +
+        'may cause unexpected scrolling behavior.',
+    );
+  }
+
   _textInputFocusError() {
     console.warn('Error measuring text field.');
   }

packages/react-native/Libraries/Components/ScrollView/ScrollViewNativeComponent.js

@@ -86,6 +86,8 @@ export const __INTERNAL_VIEW_CONFIG: PartialViewConfig =
           borderLeftColor: {
             process: require('../../StyleSheet/processColor').default,
           },
+          scrollSnapType: true,
+          scrollPadding: true,
           pointerEvents: true,
           isInvertedVirtualizedList: true,
         },
@@ -152,6 +154,8 @@ export const __INTERNAL_VIEW_CONFIG: PartialViewConfig =
           showsHorizontalScrollIndicator: true,
           showsVerticalScrollIndicator: true,
           showsScrollIndex: true,
+          scrollSnapType: true,
+          scrollPadding: true,
           snapToAlignment: true,
           snapToEnd: true,
           snapToInterval: true,

packages/react-native/Libraries/Components/ScrollView/ScrollViewNativeComponentType.js

@@ -69,6 +69,8 @@ export type ScrollViewNativeProps = $ReadOnly<{
   scrollPerfTag?: ?string,
   scrollToOverflowEnabled?: ?boolean,
   scrollsToTop?: ?boolean,
+  scrollSnapType?: ?('mandatory' | 'none'),
+  scrollPadding?: ?number,
   sendMomentumEvents?: ?boolean,
   showsHorizontalScrollIndicator?: ?boolean,
   showsScrollIndex?: ?boolean,

packages/react-native/Libraries/Components/TV/TVViewPropTypes.js

@@ -124,4 +124,11 @@ export type TVViewProps = $ReadOnly<{|
    *
    */
   nextFocusUp?: ?number,
+
+  /**
+   * Scroll snap alignment (used with scrollSnapType in ScrollView).
+   *
+   */
+  scrollSnapAlign?: ?('start' | 'center' | 'end'),
+
 |}>;

packages/react-native/Libraries/Components/View/View.js

@@ -153,6 +153,12 @@ component View(
     delete processedProps.isTVSelectable;
   }
 
+  // Views with scrollSnapAlign must not be flattened by Fabric, otherwise
+  // the prop never reaches the native view and scroll snapping breaks.
+  if (processedProps.scrollSnapAlign != null) {
+    processedProps.collapsable = false;
+  }
+
   const actualView =
     ref == null ? (
       <ViewNativeComponent {...processedProps} />

packages/react-native/Libraries/NativeComponent/TVViewConfig.js

@@ -25,5 +25,6 @@ export const validAttributesForTVProps = {
   trapFocusRight: true,
   trapFocusDown: true,
   trapFocusUp: true,
+  scrollSnapAlign: true,
 };
 

packages/react-native/React/Fabric/Mounting/ComponentViews/ScrollView/RCTEnhancedScrollView.h

@@ -51,6 +51,7 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic, assign) BOOL snapToStart;
 @property (nonatomic, assign) BOOL snapToEnd;
 @property (nonatomic, copy) NSArray<NSNumber *> *snapToOffsets;
+@property (nonatomic, assign) BOOL scrollSnapEnabled;
 
 /*
  * Makes `setContentOffset:` method no-op when given `block` is executed.

packages/react-native/React/Fabric/Mounting/ComponentViews/ScrollView/RCTEnhancedScrollView.mm

@@ -132,6 +132,9 @@ - (void)setPrivateDelegate:(id<UIScrollViewDelegate>)delegate
 
 - (id<UIScrollViewDelegate>)delegate
 {
+  if (_scrollSnapEnabled) {
+    return [super delegate];
+  }
   return _publicDelegate;
 }
 

packages/react-native/React/Fabric/Mounting/ComponentViews/ScrollView/RCTScrollViewComponentView.mm

@@ -30,6 +30,7 @@
 #import <React/RCTTVRemoteHandler.h>
 #import <React/RCTTVNavigationEventNotification.h>
 #import "React/RCTI18nUtil.h"
+#import "RCTViewComponentView.h"
 #endif
 
 using namespace facebook::react;
@@ -40,6 +41,7 @@
 
 static const CGFloat kClippingLeeway = 44.0;
 static const float TV_DEFAULT_SWIPE_DURATION = 0.3;
+static const CGPoint NO_PREFERRED_CONTENT_OFFSET = CGPointMake(CGFLOAT_MIN, CGFLOAT_MIN);
 
 static UIScrollViewKeyboardDismissMode RCTUIKeyboardDismissModeFromProps(const ScrollViewProps &props)
 {
@@ -97,6 +99,8 @@ @interface RCTScrollViewComponentView () <
     RCTScrollableProtocol,
     RCTEnhancedScrollViewOverridingDelegate>
 
+@property (nonatomic, assign) CGPoint preferredContentOffset;
+
 @end
 
 @implementation RCTScrollViewComponentView {
@@ -172,6 +176,7 @@ - (instancetype)initWithFrame:(CGRect)frame
     _endDraggingSensitivityMultiplier = 1;
 
     _tvRemoteGestureRecognizers = [NSMutableDictionary new];
+      _preferredContentOffset = NO_PREFERRED_CONTENT_OFFSET;
   }
 
   return self;
@@ -465,6 +470,13 @@ - (void)updateProps:(const Props::Shared &)props oldProps:(const Props::Shared &
     scrollView.keyboardDismissMode = RCTUIKeyboardDismissModeFromProps(newScrollViewProps);
   }
 
+#if TARGET_OS_TV
+  if (oldScrollViewProps.scrollSnapType != newScrollViewProps.scrollSnapType) {
+    scrollView.scrollSnapEnabled = newScrollViewProps.scrollSnapType.has_value() &&
+        newScrollViewProps.scrollSnapType.value() == "mandatory";
+  }
+#endif
+
   [super updateProps:props oldProps:oldProps];
 }
 
@@ -722,7 +734,10 @@ - (void)scrollViewWillEndDragging:(UIScrollView *)scrollView
                      withVelocity:(CGPoint)velocity
               targetContentOffset:(inout CGPoint *)targetContentOffset
 {
-  if (fabs(_endDraggingSensitivityMultiplier - 1) > 0.0001f) {
+    if (!CGPointEqualToPoint(self.preferredContentOffset, NO_PREFERRED_CONTENT_OFFSET))
+    {
+        *targetContentOffset = self.preferredContentOffset;
+    } else if (fabs(_endDraggingSensitivityMultiplier - 1) > 0.0001f) {
     if (targetContentOffset->y > 0) {
       const CGFloat travel = targetContentOffset->y - scrollView.contentOffset.y;
       targetContentOffset->y = scrollView.contentOffset.y + travel * _endDraggingSensitivityMultiplier;
@@ -974,6 +989,18 @@ - (void)scrollToEnd:(BOOL)animated
   [self scrollToOffset:offset animated:animated];
 }
 
+// Custom animation curve
+- (void)setContentOffset:(CGPoint)offset animated:(BOOL)animated
+{
+  if (animated) {
+    [UIView animateWithDuration:0.8 delay:0 usingSpringWithDamping:1.0 initialSpringVelocity:0 options:UIViewAnimationOptionCurveEaseInOut animations:^{
+      [_scrollView setContentOffset:offset animated:NO];
+    } completion:nil];
+  } else {
+    [_scrollView setContentOffset:offset animated:NO];
+   }
+}
+
 #pragma mark - Child views mounting
 
 - (void)updateClippedSubviewsWithClipRect:(CGRect)clipRect relativeToView:(UIView *)clipView
@@ -1034,7 +1061,7 @@ - (void)scrollToOffset:(CGPoint)offset animated:(BOOL)animated
 
   [self _forceDispatchNextScrollEvent];
 
-  [_scrollView setContentOffset:offset animated:animated];
+  [self setContentOffset:offset animated:animated];
 
   if (!animated) {
     // When not animated, the expected workflow in ``scrollViewDidEndScrollingAnimation`` after scrolling is not going
@@ -1137,19 +1164,109 @@ - (void)_adjustForMaintainVisibleContentPosition
 #pragma mark Apple TV swipe and focus handling
 
 #if TARGET_OS_TV
+// Focus marker helper: traverses view hierarchy to find scrollSnapAlign prop
+// Returns the view that has the property via the output parameter
+- (NSString *)findScrollSnapAlignInView:(UIView *)view foundView:(UIView **)outView
+{
+    UIView *testView = view;
+    UIView *snapTarget;
+    NSString *marker;
+
+    while (testView && testView != self) {
+        if (![testView isKindOfClass:RCTViewComponentView.class])
+        {
+            testView = [testView superview];
+            continue;
+        }
+        RCTViewComponentView *componentView = (RCTViewComponentView *)testView;
+
+        const auto &viewProps = static_cast<const facebook::react::BaseViewProps &>(*componentView.props);
+        if (viewProps.scrollSnapAlign.has_value() && !viewProps.scrollSnapAlign.value().empty()) {
+            marker = [NSString stringWithUTF8String:viewProps.scrollSnapAlign.value().c_str()];
+            snapTarget = componentView;
+        }
+
+        testView = [testView superview];
+    }
+    *outView = snapTarget;
+    return marker;
+}
+
+- (void)_handleScrollSnapForFocusedView:(UIView *)focusedView
+{
+    const auto &scrollProps = static_cast<const ScrollViewProps &>(*_props);
+    UIView *snapAlignView = nil;
+    NSString *scrollSnapAlign = [self findScrollSnapAlignInView:focusedView foundView:&snapAlignView];
+    if (scrollSnapAlign == nil || snapAlignView == nil) {
+        return;
+    }
+
+    RCTEnhancedScrollView *scrollView = (RCTEnhancedScrollView *)_scrollView;
+    CGRect focusedFrame = [snapAlignView convertRect:snapAlignView.bounds toView:_scrollView];
+    CGFloat targetOffset;
+    CGFloat scrollPadding = scrollProps.scrollPadding;
+
+    BOOL isHorizontalSnap = _scrollView.contentSize.width > self.frame.size.width;
+    // Determine axis-specific properties
+    CGFloat viewportSize, focusedOrigin, focusedSize, currentOffset, maxContentSize;
+    if (isHorizontalSnap) {
+        viewportSize = scrollView.bounds.size.width;
+        focusedOrigin = focusedFrame.origin.x;
+        focusedSize = focusedFrame.size.width;
+        currentOffset = scrollView.contentOffset.x;
+        maxContentSize = scrollView.contentSize.width;
+    } else {
+        viewportSize = scrollView.bounds.size.height;
+        focusedOrigin = focusedFrame.origin.y;
+        focusedSize = focusedFrame.size.height;
+        currentOffset = scrollView.contentOffset.y;
+        maxContentSize = scrollView.contentSize.height;
+    }
+    // Calculate target offset based on scrollSnapAlign (unified for both axes)
+    if ([scrollSnapAlign isEqualToString:@"start"]) {
+        targetOffset = focusedOrigin - scrollPadding;
+    } else if ([scrollSnapAlign isEqualToString:@"center"]) {
+        CGFloat viewportCenter = viewportSize / 2;
+        CGFloat focusedCenter = focusedOrigin + (focusedSize / 2);
+        targetOffset = focusedCenter - viewportCenter + (scrollPadding / 2);
+    } else if ([scrollSnapAlign isEqualToString:@"end"]) {
+        targetOffset = (focusedOrigin + focusedSize) - viewportSize + scrollPadding;
+    } else {
+        targetOffset = currentOffset;
+    }
+
+    // Apply snap-to-interval if configured
+    if (scrollView.snapToInterval > 0) {
+        CGFloat interval = scrollView.snapToInterval;
+        targetOffset = floor(targetOffset / interval) * interval;
+    }
+
+    // Clamp to valid range
+    CGFloat maxOffset = MAX(maxContentSize - viewportSize, 0);
+    targetOffset = MAX(0, MIN(targetOffset, maxOffset));
+    CGPoint targetContentOffset = isHorizontalSnap
+        ? CGPointMake(targetOffset, scrollView.contentOffset.y)
+        : CGPointMake(scrollView.contentOffset.x, targetOffset);
+    self.preferredContentOffset = targetContentOffset;
+    [self setContentOffset:targetContentOffset animated:YES];
+}
+
 - (void)didUpdateFocusInContext:(UIFocusUpdateContext *)context
        withAnimationCoordinator:(UIFocusAnimationCoordinator *)coordinator
 {
-    if (context.previouslyFocusedView == context.nextFocusedView || !_props->isTVSelectable) {
+    self.preferredContentOffset = NO_PREFERRED_CONTENT_OFFSET;
+    const auto &scrollProps = static_cast<const ScrollViewProps &>(*_props);
+    BOOL hasScrollSnapType = scrollProps.scrollSnapType.has_value() && scrollProps.scrollSnapType.value() == "mandatory";
+    if (context.previouslyFocusedView == context.nextFocusedView || (!_props->isTVSelectable && !hasScrollSnapType)) {
         return;
     }
-    if (context.nextFocusedView == self) {
+    if (_props->isTVSelectable && context.nextFocusedView == self) {
         [self becomeFirstResponder];
         [self addSwipeGestureRecognizers];
         // if we enter the scroll view from different view then block first touch event since it is the event that triggered the focus
         _blockFirstTouch = (unsigned long)context.focusHeading != 0;
         [self addArrowsListeners];
-    } else if (context.previouslyFocusedView == self) {
+    } else if (_props->isTVSelectable && context.previouslyFocusedView == self) {
         [self removeArrowsListeners];
         [self removeSwipeGestureRecognizers];
         [self resignFirstResponder];
@@ -1171,6 +1288,8 @@ - (void)didUpdateFocusInContext:(UIFocusUpdateContext *)context
                 [self scrollToHorizontalOffset:scrollView.contentSize.width];
             }
         }
+    } else if ([context.nextFocusedView isDescendantOfView:_scrollView]) {
+        [self _handleScrollSnapForFocusedView:context.nextFocusedView];
     }
 }