feat(ios): add scroll edge effect support for iOS 26+ (#595)

* feat(ios): add scroll edge effect support for iOS 26+

Add topScrollEdgeEffect and bottomScrollEdgeEffect to
scrollableOptions for UIScrollEdgeEffect style control.

* docs: update changelog for scroll edge effect

* feat(ios): add scroll edge element container interaction for header/footer

Use UIScrollEdgeElementContainerInteraction on iOS 26+ to apply
automatic blur/gradient edge effects on header and footer views
when content scrolls behind them.

* feat(ios): default scroll edge effect to hidden

Also update docs with scroll edge effect guide and type reference.

* fix(ios): fix hasScrollableOptions check and deduplicate edge interaction cleanup

* refactor(ios): extract edge interaction into UIView category and fix review issues

- Add @available guard for setupEdgeInteractions in setupScrollable
- Make scrollView param nullable in edge interaction methods
- Extract shared edge interaction logic into UIView+ScrollEdgeInteraction
- Remove redundant setupEdgeInteractions calls from mount/scrollViewDidChange

* chore: run tidy

Author: lodev09

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Add accessibility support to grabber view with VoiceOver/TalkBack actions and state descriptions. ([#587](https://github.com/lodev09/react-native-true-sheet/pull/587) by [@lodev09](https://github.com/lodev09))
 - Add `scrollingExpandsSheet` option to `scrollableOptions`. ([#585](https://github.com/lodev09/react-native-true-sheet/pull/585) by [@lodev09](https://github.com/lodev09))
+- **iOS**: Add `topScrollEdgeEffect` and `bottomScrollEdgeEffect` to `scrollableOptions` for iOS 26+. ([#595](https://github.com/lodev09/react-native-true-sheet/pull/595) by [@lodev09](https://github.com/lodev09))
 
 ### 🐛 Bug fixes
 

docs/docs/guides/scrolling.mdx

@@ -80,6 +80,38 @@ By default, scrolling content to the top edge expands the sheet to the next dete
 
 On iOS, this uses [`prefersScrollingExpandsWhenScrolledToEdge`](https://developer.apple.com/documentation/uikit/uisheetpresentationcontroller/3858107-prefersscrollingexpandswhenscrol). On Android, a custom `BottomSheetBehavior` selectively blocks scroll-driven expansion while preserving normal scrolling, fling deceleration, and grabber-based dragging.
 
+## Scroll Edge Effect
+
+On iOS 26+, you can apply a blur/gradient edge effect on the header and footer when content scrolls behind them. This uses [`UIScrollEdgeElementContainerInteraction`](https://developer.apple.com/documentation/uikit/uiscrolledgeelementcontainerinteraction) under the hood.
+
+Set [`topScrollEdgeEffect`](../reference/types#scrollableoptions) and/or [`bottomScrollEdgeEffect`](../reference/types#scrollableoptions) in [`scrollableOptions`](../reference/configuration#scrollableoptions) to enable it:
+
+```tsx
+<TrueSheet
+  scrollable
+  scrollableOptions={{
+    topScrollEdgeEffect: 'automatic',
+    bottomScrollEdgeEffect: 'soft',
+  }}
+  header={<Header />}
+  footer={<Footer />}
+>
+  <ScrollView>
+    <View />
+  </ScrollView>
+</TrueSheet>
+```
+
+Available values: `'automatic'`, `'hard'`, `'soft'`, or `'hidden'` (default). See [`ScrollEdgeEffect`](../reference/types#scrolledgeeffect).
+
+:::info
+This also controls the scroll view's own edge effects ([`UIScrollEdgeEffect`](https://developer.apple.com/documentation/uikit/uiscrolledgeeffect)). `topScrollEdgeEffect` applies to both the header interaction and the scroll view's top edge, and `bottomScrollEdgeEffect` applies to both the footer interaction and the scroll view's bottom edge.
+:::
+
+:::note
+This feature requires iOS 26 or later. On older versions, these options are ignored.
+:::
+
 ## Using `scrollToEnd`
 
 When using `scrollable`, the native scroll view frame is modified to fit within the sheet container. This can cause `scrollToEnd()` on `FlatList` or `ScrollView` to not work as expected because React Native's JS-side scroll metrics may not reflect the actual native dimensions.

docs/docs/reference/04-types.mdx

@@ -97,6 +97,19 @@ Options for customizing scrollable behavior. Only applies when `scrollable` is `
 | - | - | - | - |
 | `scrollingExpandsSheet` | `boolean` | When `false`, scrolling the content does not expand the sheet to the next detent. Only dragging the grabber or sheet background expands it. Useful for YouTube-style comments sheets. | `true` |
 | `keyboardScrollOffset` | `number` | Additional offset when scrolling to a focused input above the keyboard. | `0` |
+| `topScrollEdgeEffect` | [`ScrollEdgeEffect`](#scrolledgeeffect) | The scroll edge effect applied to the top edge of the scroll view and header. iOS 26+ only. | `'hidden'` |
+| `bottomScrollEdgeEffect` | [`ScrollEdgeEffect`](#scrolledgeeffect) | The scroll edge effect applied to the bottom edge of the scroll view and footer. iOS 26+ only. | `'hidden'` |
+
+## `ScrollEdgeEffect`
+
+Controls the blur/gradient edge effect on the scroll view edges and header/footer overlay views. iOS 26+ only.
+
+| Value | Description |
+| - | - |
+| `'automatic'` | System default edge effect style. |
+| `'hard'` | A hard, opaque edge effect. |
+| `'soft'` | A soft, gradient edge effect. |
+| `'hidden'` | No edge effect. This is the default. |
 
 ## `GrabberOptions`
 

example/bare/ios/Podfile.lock

@@ -2649,7 +2649,7 @@ PODS:
     - ReactCommon/turbomodule/core
     - SocketRocket
     - Yoga
-  - RNTrueSheet (3.9.9):
+  - RNTrueSheet (3.10.0-beta.1):
     - boost
     - DoubleConversion
     - fast_float
@@ -3104,7 +3104,7 @@ SPEC CHECKSUMS:
   RNGestureHandler: e1cf8ef3f11045536eed6bd4f132b003ef5f9a5f
   RNReanimated: f1868b36f4b2b52a0ed00062cfda69506f75eaee
   RNScreens: d821082c6dd1cb397cc0c98b026eeafaa68be479
-  RNTrueSheet: a3094081efc659586c568292d1b778703611a5dd
+  RNTrueSheet: cda20577e6b3553643620281ee9143f0ae6c8371
   RNWorklets: d9c050940f140af5d8b611d937eab1cbfce5e9a5
   SocketRocket: d4aabe649be1e368d1318fdf28a022d714d65748
   Yoga: 689c8e04277f3ad631e60fe2a08e41d411daf8eb

example/shared/src/components/Footer.tsx

@@ -28,16 +28,20 @@ export const Footer = ({ children, text = 'FOOTER', onPress, ...rest }: FooterPr
 
 const styles = StyleSheet.create({
   wrapper: {
-    backgroundColor: DARK_GRAY,
+    backgroundColor: Platform.select({
+      default: DARK_GRAY,
+      ios: undefined,
+    }),
   },
   container: {
     height: FOOTER_HEIGHT,
-    padding: SPACING,
+    paddingHorizontal: SPACING,
   },
   pressed: {
     opacity: 0.6,
   },
   text: {
+    marginTop: SPACING,
     textAlign: 'center',
     color: '#fff',
   },

example/shared/src/components/Input.tsx

@@ -1,4 +1,4 @@
-import { StyleSheet, TextInput, View, type TextInputProps } from 'react-native';
+import { Platform, StyleSheet, TextInput, View, type TextInputProps } from 'react-native';
 
 import { LIGHT_GRAY, INPUT_HEIGHT, SPACING } from '../utils';
 import { forwardRef } from 'react';
@@ -25,7 +25,10 @@ export const Input = forwardRef<TextInput, TextInputProps>((props, ref) => {
 
 const styles = StyleSheet.create({
   inputContainer: {
-    backgroundColor: 'rgba(0, 0, 0, 0.3)',
+    backgroundColor: Platform.select({
+      ios: 'rgba(0, 0, 0, 0.5)',
+      default: 'rgba(0, 0, 0, 0.3)',
+    }),
     paddingHorizontal: SPACING,
     height: INPUT_HEIGHT,
     borderRadius: INPUT_HEIGHT,

example/shared/src/components/sheets/FlatListSheet.tsx

@@ -2,8 +2,7 @@ import { forwardRef, useRef } from 'react';
 import { StyleSheet, FlatList, View } from 'react-native';
 import { TrueSheet, type TrueSheetProps } from '@lodev09/react-native-true-sheet';
 
-import { DARK, DARK_GRAY, FOOTER_HEIGHT, SPACING, times } from '../../utils';
-import { Input } from '../Input';
+import { DARK, DARK_GRAY, FOOTER_HEIGHT, HEADER_HEIGHT, SPACING, times } from '../../utils';
 import { DemoContent } from '../DemoContent';
 import { Spacer } from '../Spacer';
 import { Header } from '../Header';
@@ -22,11 +21,11 @@ export const FlatListSheet = forwardRef<TrueSheet, FlatListSheetProps>((props, r
       backgroundBlur="dark"
       backgroundColor={DARK}
       scrollable
-      header={
-        <Header>
-          <Input />
-        </Header>
-      }
+      scrollableOptions={{
+        bottomScrollEdgeEffect: 'soft',
+        topScrollEdgeEffect: 'soft',
+      }}
+      header={<Header style={styles.header} />}
       onDidDismiss={() => console.log('Sheet FlatList dismissed!')}
       onDidPresent={() => console.log(`Sheet FlatList presented!`)}
       footer={<Footer text="OPEN BLANK SHEET" onPress={() => testRef.current?.present()} />}
@@ -56,8 +55,15 @@ const styles = StyleSheet.create({
   wrapper: {
     flex: 1,
   },
+  header: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    zIndex: 1,
+  },
   content: {
     padding: SPACING,
+    paddingTop: HEADER_HEIGHT,
     paddingBottom: FOOTER_HEIGHT + SPACING,
   },
 });

example/shared/src/components/sheets/ScrollViewSheet.tsx

@@ -11,9 +11,19 @@ import {
 } from 'react-native';
 import { TrueSheet, type TrueSheetProps } from '@lodev09/react-native-true-sheet';
 
-import { BORDER_RADIUS, DARK, FOOTER_HEIGHT, GAP, LIGHT_GRAY, SPACING, times } from '../../utils';
+import {
+  BORDER_RADIUS,
+  DARK,
+  FOOTER_HEIGHT,
+  GAP,
+  HEADER_HEIGHT,
+  LIGHT_GRAY,
+  SPACING,
+  times,
+} from '../../utils';
 import { Footer } from '../Footer';
 import { Header } from '../Header';
+import { Button } from '../Button';
 
 interface ScrollViewSheetProps extends TrueSheetProps {}
 
@@ -55,10 +65,19 @@ export const ScrollViewSheet = forwardRef<TrueSheet, ScrollViewSheetProps>((prop
       detents={[0.8, 1]}
       name="scrollview"
       scrollable
-      scrollableOptions={{ scrollingExpandsSheet: false }}
+      scrollableOptions={{
+        scrollingExpandsSheet: false,
+        bottomScrollEdgeEffect: 'soft',
+        topScrollEdgeEffect: 'soft',
+      }}
       backgroundColor={Platform.select({ android: DARK })}
       header={<Header />}
-      footer={<Footer text="TOGGLE LISTVIEW" onPress={() => setShowList(!showList)} />}
+      headerStyle={styles.header}
+      footer={
+        <Footer>
+          <Button text="Toggle ListView" onPress={() => setShowList(!showList)} />
+        </Footer>
+      }
       onDidDismiss={() => console.log('Sheet ScrollView dismissed!')}
       onDidPresent={() => console.log(`Sheet ScrollView presented!`)}
       {...props}
@@ -89,9 +108,16 @@ ScrollViewSheet.displayName = 'ScrollViewSheet';
 const styles = StyleSheet.create({
   content: {
     padding: SPACING,
+    paddingTop: HEADER_HEIGHT,
     paddingBottom: FOOTER_HEIGHT + SPACING,
     gap: GAP,
   },
+  header: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    zIndex: 1,
+  },
   item: {
     backgroundColor: 'rgba(0, 0, 0, 0.3)',
     borderRadius: BORDER_RADIUS,

ios/TrueSheetContainerView.h

@@ -17,6 +17,8 @@ NS_ASSUME_NONNULL_BEGIN
 
 @property (nonatomic, assign) CGFloat keyboardScrollOffset;
 @property (nonatomic, assign) BOOL scrollingExpandsSheet;
+@property (nonatomic, assign) NSInteger topScrollEdgeEffect;
+@property (nonatomic, assign) NSInteger bottomScrollEdgeEffect;
 
 @end
 

ios/TrueSheetContainerView.mm

@@ -9,11 +9,13 @@
 #ifdef RCT_NEW_ARCH_ENABLED
 
 #import "TrueSheetContainerView.h"
+#import <React/RCTScrollViewComponentView.h>
 #import "TrueSheetContentView.h"
 #import "TrueSheetFooterView.h"
 #import "TrueSheetHeaderView.h"
 #import "TrueSheetViewController.h"
 #import "core/TrueSheetKeyboardObserver.h"
+#import "utils/UIView+ScrollEdgeInteraction.h"
 #import "utils/WindowUtil.h"
 
 #import <react/renderer/components/TrueSheetSpec/ComponentDescriptors.h>
@@ -33,6 +35,8 @@ - (instancetype)init {
   if (self = [super init]) {
     _keyboardScrollOffset = 0;
     _scrollingExpandsSheet = YES;
+    _topScrollEdgeEffect = (NSInteger)TrueSheetViewTopScrollEdgeEffect::Hidden;
+    _bottomScrollEdgeEffect = (NSInteger)TrueSheetViewBottomScrollEdgeEffect::Hidden;
   }
   return self;
 }
@@ -111,6 +115,34 @@ - (void)setupScrollable {
       bottomInset = [WindowUtil keyWindow].safeAreaInsets.bottom;
     }
     [_contentView setupScrollable:_scrollableEnabled bottomInset:bottomInset];
+    [_contentView applyScrollEdgeEffects:_scrollableOptions];
+    if (@available(iOS 26.0, *)) {
+      [self setupEdgeInteractions];
+    }
+  }
+}
+
+- (void)setupEdgeInteractions API_AVAILABLE(ios(26.0)) {
+  if (!_contentView) {
+    return;
+  }
+
+  NSInteger topEffect =
+    _scrollableOptions ? _scrollableOptions.topScrollEdgeEffect : (NSInteger)TrueSheetViewTopScrollEdgeEffect::Hidden;
+  NSInteger bottomEffect = _scrollableOptions ? _scrollableOptions.bottomScrollEdgeEffect
+                                              : (NSInteger)TrueSheetViewBottomScrollEdgeEffect::Hidden;
+
+  BOOL topHidden = topEffect == (NSInteger)TrueSheetViewTopScrollEdgeEffect::Hidden;
+  BOOL bottomHidden = bottomEffect == (NSInteger)TrueSheetViewBottomScrollEdgeEffect::Hidden;
+
+  RCTScrollViewComponentView *scrollViewComponent = [_contentView findScrollView];
+  UIScrollView *scrollView = scrollViewComponent.scrollView;
+
+  if (_headerView) {
+    [_headerView setupEdgeInteractionWithScrollView:topHidden ? nil : scrollView edge:UIRectEdgeTop];
+  }
+  if (_footerView) {
+    [_footerView setupEdgeInteractionWithScrollView:bottomHidden ? nil : scrollView edge:UIRectEdgeBottom];
   }
 }