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/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/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.mm

@@ -132,7 +132,7 @@ - (void)setPrivateDelegate:(id<UIScrollViewDelegate>)delegate
 
 - (id<UIScrollViewDelegate>)delegate
 {
-  return _publicDelegate;
+  return [super delegate];
 }
 
 - (void)setDelegate:(id<UIScrollViewDelegate>)delegate

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;
@@ -722,7 +727,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 +982,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 +1054,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 +1157,50 @@ - (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)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 +1222,60 @@ - (void)didUpdateFocusInContext:(UIFocusUpdateContext *)context
                 [self scrollToHorizontalOffset:scrollView.contentSize.width];
             }
         }
+    } else if ([context.nextFocusedView isDescendantOfView:_scrollView]) {
+        // Focus marker-based scrolling: Check if the focused view has a scrollSnapAlign
+        UIView *snapAlignView = nil;
+        NSString *scrollSnapAlign = [self findScrollSnapAlignInView:context.nextFocusedView foundView:&snapAlignView];
+        if (scrollSnapAlign != nil && snapAlignView != nil) {
+            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];
+        }
     }
 }
 

packages/react-native/React/Fabric/Mounting/ComponentViews/View/RCTViewComponentView.h

@@ -80,6 +80,8 @@ NS_ASSUME_NONNULL_BEGIN
 @property(nonatomic, nullable) UIFocusGuide *focusGuideLeft;
 @property(nonatomic, nullable) UIFocusGuide *focusGuideRight;
 @property(nonatomic, nullable, strong) RCTTVRemoteSelectHandler *tvRemoteSelectHandler;
+
+- (NSString *)scrollSnapAlign;
 #endif
 
 /**

packages/react-native/React/Fabric/Mounting/ComponentViews/View/RCTViewComponentView.mm

@@ -87,6 +87,7 @@ @implementation RCTViewComponentView {
   BOOL _trapFocusRight;
   NSArray* _focusDestinations;
   id<UIFocusItem> _previouslyFocusedItem;
+  NSString *_scrollSnapAlign;
   RCTSwiftUIContainerViewWrapper *_swiftUIWrapper;
   BOOL _shouldFocusOnMount;
 }
@@ -441,6 +442,13 @@ - (void)removeParallaxMotionEffects
   _motionEffectsAdded = NO;
 }
 
+- (NSString *)scrollSnapAlign
+{
+#if TARGET_OS_TV
+  return _scrollSnapAlign;
+#endif
+  return nil;
+}
 
 - (BOOL)isTVFocusGuide
 {
@@ -1170,6 +1178,15 @@ - (void)updateProps:(const Props::Shared &)props oldProps:(const Props::Shared &
   _trapFocusDown = newViewProps.trapFocusDown;
   _trapFocusLeft = newViewProps.trapFocusLeft;
   _trapFocusRight = newViewProps.trapFocusRight;
+
+  // `scrollSnapAlign`
+  if (oldViewProps.scrollSnapAlign != newViewProps.scrollSnapAlign) {
+    if (newViewProps.scrollSnapAlign.has_value()) {
+      _scrollSnapAlign = [[NSString alloc] initWithUTF8String:newViewProps.scrollSnapAlign.value().c_str()];
+    } else {
+      _scrollSnapAlign = nil;
+    }
+  }
 #endif
 
   _needsInvalidateLayer = _needsInvalidateLayer || needsInvalidateLayer;