@onekeyfe/react-native-native-list 3.0.177 → 3.0.179-alpha.20261015

package/android/src/main/java/com/onekey/nativelist/HybridNativeList.kt

@@ -31,6 +31,9 @@ class HybridNativeList(context: ThemedReactContext) : HybridNativeListSpec() {
       dispatchToUi { hostView.setContainerSlotHeightsJson(value) }
     }
 
+  override var topScrollEdgeHard: Boolean = false
+  override var topOverlayHeight: Double = 0.0
+
   override var snapshotJson: String = ""
     get() = field
     set(value) {

package/docs/SPEC.md

@@ -26,6 +26,25 @@ prevention; there is no automatic fitting or shrinking pass.
 
 ## Public API and defaults
 
+### iOS 26 fixed top scroll-edge overlay
+
+Standalone `NativeList` accepts optional `topScrollEdgeEffect="hard"` and
+`topOverlay` React content. Both are disabled by default. On iOS 26 or newer,
+the fixed overlay is a fourth native container slot, outside the row stream and
+outside the existing scrolling `listHeader`/`listEmpty`/`listFooter` slots.
+Fabric measures its height; the list owns an equal top inset on its collection
+view and binds UIKit's `UIScrollEdgeElementContainerInteraction` to that view,
+using the hard top edge style. The list restores its original inset and effect
+on removal, disposal and reuse. The UI thread owns all view and UIKit state;
+there is no persistence, background-runtime state or per-frame JS callback.
+An invisible, noninteractive native label fills the overlay host so UIKit
+recognizes React-drawn content as a scroll-edge element.
+Inside a CollapsiblePagerView, the pager owns this effect and inset, and child
+lists do not opt in separately. iOS before 26, Android and Web retain their
+existing layout and scrolling. Missing overlay or style changes nothing.
+Acceptance requires actual iOS 26 initial layout, long/short/empty scrolling,
+refresh and overlay replacement/removal, including dark mode.
+
 [README.md](../README.md) documents the snapshot, patch, selection, events and
 imperative API; [STYLE_SPEC.md](STYLE_SPEC.md) defines normalization, omitted
 style defaults and platform differences. Height precedence is

package/ios/HybridNativeList.swift

@@ -36,6 +36,24 @@ final class HybridNativeList: HybridNativeListSpec {
     }
   }
 
+  var topScrollEdgeHard = false {
+    didSet {
+      runOnMain { [weak self] in
+        self?.hostView?.setTopScrollEdge(hard: self?.topScrollEdgeHard ?? false,
+                                     overlayHeight: CGFloat(self?.topOverlayHeight ?? 0))
+      }
+    }
+  }
+
+  var topOverlayHeight: Double = 0 {
+    didSet {
+      runOnMain { [weak self] in
+        self?.hostView?.setTopScrollEdge(hard: self?.topScrollEdgeHard ?? false,
+                                     overlayHeight: CGFloat(self?.topOverlayHeight ?? 0))
+      }
+    }
+  }
+
   var snapshotJson: String = "" {
     didSet {
       guard snapshotJson != oldValue else { return }

package/ios/RNCNativeListView.swift

@@ -11,11 +11,27 @@ final class NativeListView: UIView {
   // Each root therefore lives in a list-owned host whose origin the list alone controls, so a
   // React layout update can never move a slot out of its native position, even for a frame.
   private var reactContainerSlots: [(content: UIView, host: UIView)] = []
+  private let topOverlayHost = UIView()
+  private weak var topOverlayContent: UIView?
+  private var topEdgeInteraction: UIInteraction?
+  private var topEdgeMarker: UILabel?
+  private var originalTopEdgeStyle: AnyObject?
+  private var topScrollEdgeHard = false
+  private var requestedTopOverlayHeight: CGFloat = 0
+  private var appliedTopOverlayInset: CGFloat = 0
+
   private var lastLaidOutContentHeight: CGFloat?
   private var needsContentShrinkCorrection = false
   private var contentShrinkCorrectionScheduled = false
 
   @objc func mountContainerSlot(_ view: UIView, atIndex index: Int) {
+    if index == 3 {
+      topOverlayContent?.removeFromSuperview()
+      topOverlayContent = view
+      topOverlayHost.addSubview(view)
+      updateTopScrollEdge()
+      return
+    }
     let host = UIView()
     // Clipping to the reported height keeps new content from overlapping rows until the list
     // has reserved space for it.
@@ -28,6 +44,12 @@ final class NativeListView: UIView {
   }
 
   @objc func unmountContainerSlot(_ view: UIView) {
+    if topOverlayContent === view {
+      view.removeFromSuperview()
+      topOverlayContent = nil
+      updateTopScrollEdge()
+      return
+    }
     reactContainerSlots.removeAll { slot in
       guard slot.content === view else { return false }
       view.removeFromSuperview()
@@ -36,6 +58,66 @@ final class NativeListView: UIView {
     }
   }
 
+  func setTopScrollEdge(hard: Bool, overlayHeight: CGFloat) {
+    topScrollEdgeHard = hard
+    requestedTopOverlayHeight = overlayHeight.isFinite ? max(0, overlayHeight) : 0
+    updateTopScrollEdge()
+    setNeedsLayout()
+  }
+
+  private func updateTopScrollEdge() {
+    if #available(iOS 26.0, *) {
+      let hasOverlay = topScrollEdgeHard && topOverlayContent != nil
+      let enabled = hasOverlay && window != nil
+      let nextInset = hasOverlay ? requestedTopOverlayHeight : 0
+      if nextInset != appliedTopOverlayInset {
+        // Do not interrupt UIKit's rebound after a refresh has ended.
+        let wasReturningFromPull =
+          collectionView.contentOffset.y < -collectionView.adjustedContentInset.top - 0.5
+        let logicalOffset = collectionView.contentOffset.y + collectionView.contentInset.top
+        var inset = collectionView.contentInset
+        inset.top += nextInset - appliedTopOverlayInset
+        collectionView.contentInset = inset
+        appliedTopOverlayInset = nextInset
+        if !wasReturningFromPull {
+          collectionView.setContentOffset(
+            CGPoint(x: collectionView.contentOffset.x, y: logicalOffset - inset.top),
+            animated: false)
+        }
+      }
+      if enabled && topEdgeInteraction == nil {
+        originalTopEdgeStyle = collectionView.topEdgeEffect.style
+        // UIKit needs a native element to shape the edge effect around React-drawn content.
+        let marker = UILabel(frame: topOverlayHost.bounds)
+        marker.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        marker.text = " "
+        marker.textColor = .clear
+        marker.backgroundColor = .clear
+        marker.isUserInteractionEnabled = false
+        marker.isAccessibilityElement = false
+        marker.accessibilityElementsHidden = true
+        topOverlayHost.addSubview(marker)
+        topEdgeMarker = marker
+        let interaction = UIScrollEdgeElementContainerInteraction()
+        interaction.edge = .top
+        interaction.scrollView = collectionView
+        topOverlayHost.addInteraction(interaction)
+        topEdgeInteraction = interaction
+      } else if !enabled, let interaction = topEdgeInteraction {
+        topOverlayHost.removeInteraction(interaction)
+        (interaction as? UIScrollEdgeElementContainerInteraction)?.scrollView = nil
+        topEdgeInteraction = nil
+        topEdgeMarker?.removeFromSuperview()
+        topEdgeMarker = nil
+        if let originalTopEdgeStyle = originalTopEdgeStyle as? UIScrollEdgeEffect.Style {
+          collectionView.topEdgeEffect.style = originalTopEdgeStyle
+        }
+        originalTopEdgeStyle = nil
+      }
+      if enabled { collectionView.topEdgeEffect.style = .hard }
+    }
+  }
+
   func setContainerSlotHeightsJson(_ json: String) {
     guard let data = json.data(using: .utf8),
           let heights = try? JSONSerialization.jsonObject(with: data) as? [Double],
@@ -271,6 +353,7 @@ final class NativeListView: UIView {
     addSubview(footerContainer)
     addSubview(sectionIndexView)
     addSubview(sectionIndexPreview)
+    addSubview(topOverlayHost)
     footerContainer.addSubview(footerCell)
     collectionView.translatesAutoresizingMaskIntoConstraints = false
     footerContainer.translatesAutoresizingMaskIntoConstraints = false
@@ -422,11 +505,14 @@ final class NativeListView: UIView {
 
   override func didMoveToWindow() {
     super.didMoveToWindow()
+    updateTopScrollEdge()
     updateSectionIndexAttachment()
   }
 
   override func layoutSubviews() {
     super.layoutSubviews()
+    topOverlayHost.frame = CGRect(x: 0, y: 0, width: collectionView.bounds.width,
+                                  height: requestedTopOverlayHeight)
     updateSectionIndexAttachment()
     let direction = effectiveUserInterfaceLayoutDirection
     if let lastLayoutSize,
@@ -1998,6 +2084,7 @@ final class NativeListView: UIView {
 
   func dispose() {
     guard !disposed else { return }
+    setTopScrollEdge(hard: false, overlayHeight: 0)
     disposed = true
 
     disposeActionAnchor()

package/lib/module/NativeList.js

@@ -3,12 +3,12 @@
 import React, { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import { OneKeyImageCache, OneKeyImageCachePolicy } from '@onekeyfe/react-native-image';
 import { NativeAvatarPrefetchModel, NativeAvatarPrefetchQueue } from "./avatarPrefetch.js";
-import { View } from 'react-native';
+import { Platform, View } from 'react-native';
 import { callback, getHostComponent } from 'react-native-nitro-modules';
 import { isSelectableRow } from "./selection.js";
 import { normalizeIndexScroll, normalizeKeyScroll, normalizePositionScroll, resolveLocationIndex, scrollFailure, validateOffset } from "./scrolling.js";
 import { applyRowPatches, serializePatches, serializeSnapshot } from "./validation.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const NativeListConfig = require('../nitrogen/generated/shared/json/NativeListConfig.json');
 const NativeListHost = getHostComponent('NativeList', () => NativeListConfig);
 export function preloadNativeListAvatarImages(sources) {
@@ -30,6 +30,8 @@ export const NativeList = /*#__PURE__*/forwardRef(function NativeList({
   listHeader,
   listFooter,
   listEmpty,
+  topOverlay,
+  topScrollEdgeEffect,
   scrollPositionThresholds,
   webVirtualizationEnabled: _webVirtualizationEnabled,
   webSectionIndexContainerRef: _webSectionIndexContainerRef,
@@ -51,6 +53,8 @@ export const NativeList = /*#__PURE__*/forwardRef(function NativeList({
   ...viewProps
 }, forwardedRef) {
   const [slotHeights, setSlotHeights] = useState([0, 0, 0]);
+  const [topOverlayHeight, setTopOverlayHeight] = useState(0);
+  const hasTopOverlay = Platform?.OS === 'ios' && Number(Platform.Version) >= 26 && topScrollEdgeEffect === 'hard' && topOverlay != null;
   const containerSlotHeightsJson = JSON.stringify(slotHeights);
   const slotInset = snapshot.layout.contentPaddingHorizontal ?? snapshot.layout.contentPadding ?? 0;
   if (snapshot.layout.orientation === 'horizontal' && (listHeader || listEmpty || listFooter)) {
@@ -313,15 +317,17 @@ export const NativeList = /*#__PURE__*/forwardRef(function NativeList({
       callbacksRef.current.onVisibleRangeChanged?.(payload);
     })
   }), []);
-  return /*#__PURE__*/_jsx(NativeListHost, {
+  return /*#__PURE__*/_jsxs(NativeListHost, {
     ...viewProps,
     ...nativeCallbacks,
     snapshotJson: snapshotJson,
     containerSlotHeightsJson: containerSlotHeightsJson,
+    topScrollEdgeHard: hasTopOverlay,
+    topOverlayHeight: hasTopOverlay ? topOverlayHeight : 0,
     scrollPositionThresholdsJson: scrollPositionThresholdsJson,
     keyboardDismissMode: keyboardDismissMode,
     keyboardShouldPersistTaps: normalizedKeyboardShouldPersistTaps,
-    children: slotContents.map((content, index) => /*#__PURE__*/_jsx(View, {
+    children: [slotContents.map((content, index) => /*#__PURE__*/_jsx(View, {
       collapsable: false,
       style: {
         position: 'absolute',
@@ -334,7 +340,20 @@ export const NativeList = /*#__PURE__*/forwardRef(function NativeList({
         setSlotHeights(previous => previous[index] === height ? previous : previous.map((value, slot) => slot === index ? height : value));
       },
       children: content
-    }, index))
+    }, index)), hasTopOverlay ? /*#__PURE__*/_jsx(View, {
+      collapsable: false,
+      style: {
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0
+      },
+      onLayout: event => {
+        const height = Math.ceil(event.nativeEvent.layout.height);
+        setTopOverlayHeight(previous => previous === height ? previous : height);
+      },
+      children: topOverlay
+    }) : null]
   });
 });
 //# sourceMappingURL=NativeList.js.map

package/lib/module/NativeList.web.js

@@ -25,6 +25,8 @@ export const NativeList = /*#__PURE__*/forwardRef(function NativeList({
   listHeader: _listHeader,
   listEmpty: _listEmpty,
   listFooter: _listFooter,
+  topOverlay: _topOverlay,
+  topScrollEdgeEffect: _topScrollEdgeEffect,
   scrollPositionThresholds: _scrollPositionThresholds,
   onScrollPositionThresholdChange: _onScrollPositionThresholdChange,
   webVirtualizationEnabled = true,

package/lib/nitrogen/generated/android/c++/JHybridNativeListSpec.cpp

@@ -75,6 +75,24 @@ namespace margelo::nitro::nativelist {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<jni::JString> /* containerSlotHeightsJson */)>("setContainerSlotHeightsJson");
     method(_javaPart, jni::make_jstring(containerSlotHeightsJson));
   }
+  bool JHybridNativeListSpec::getTopScrollEdgeHard() {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jboolean()>("getTopScrollEdgeHard");
+    auto __result = method(_javaPart);
+    return static_cast<bool>(__result);
+  }
+  void JHybridNativeListSpec::setTopScrollEdgeHard(bool topScrollEdgeHard) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(jboolean /* topScrollEdgeHard */)>("setTopScrollEdgeHard");
+    method(_javaPart, topScrollEdgeHard);
+  }
+  double JHybridNativeListSpec::getTopOverlayHeight() {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<double()>("getTopOverlayHeight");
+    auto __result = method(_javaPart);
+    return __result;
+  }
+  void JHybridNativeListSpec::setTopOverlayHeight(double topOverlayHeight) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(double /* topOverlayHeight */)>("setTopOverlayHeight");
+    method(_javaPart, topOverlayHeight);
+  }
   std::string JHybridNativeListSpec::getScrollPositionThresholdsJson() {
     static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<jni::JString>()>("getScrollPositionThresholdsJson");
     auto __result = method(_javaPart);

package/lib/nitrogen/generated/android/c++/JHybridNativeListSpec.hpp

@@ -54,6 +54,10 @@ namespace margelo::nitro::nativelist {
     void setSnapshotJson(const std::string& snapshotJson) override;
     std::string getContainerSlotHeightsJson() override;
     void setContainerSlotHeightsJson(const std::string& containerSlotHeightsJson) override;
+    bool getTopScrollEdgeHard() override;
+    void setTopScrollEdgeHard(bool topScrollEdgeHard) override;
+    double getTopOverlayHeight() override;
+    void setTopOverlayHeight(double topOverlayHeight) override;
     std::string getScrollPositionThresholdsJson() override;
     void setScrollPositionThresholdsJson(const std::string& scrollPositionThresholdsJson) override;
     std::optional<std::function<void(bool /* isBeyondThreshold */)>> getOnScrollPositionThresholdChange() override;

package/lib/nitrogen/generated/android/c++/views/JHybridNativeListStateUpdater.cpp

@@ -63,6 +63,16 @@ void JHybridNativeListStateUpdater::updateViewProps(jni::alias_ref<jni::JClass>
         : !newProps->containerSlotHeightsJson.hasSameValue(oldProps->containerSlotHeightsJson)) {
     hybridView->setContainerSlotHeightsJson(newProps->containerSlotHeightsJson.get());
   }
+  if (oldProps == nullptr
+        ? newProps->topScrollEdgeHard.isProvided()
+        : !newProps->topScrollEdgeHard.hasSameValue(oldProps->topScrollEdgeHard)) {
+    hybridView->setTopScrollEdgeHard(newProps->topScrollEdgeHard.get());
+  }
+  if (oldProps == nullptr
+        ? newProps->topOverlayHeight.isProvided()
+        : !newProps->topOverlayHeight.hasSameValue(oldProps->topOverlayHeight)) {
+    hybridView->setTopOverlayHeight(newProps->topOverlayHeight.get());
+  }
   if (oldProps == nullptr
         ? newProps->scrollPositionThresholdsJson.isProvided()
         : !newProps->scrollPositionThresholdsJson.hasSameValue(oldProps->scrollPositionThresholdsJson)) {

package/lib/nitrogen/generated/android/kotlin/com/margelo/nitro/nativelist/HybridNativeListSpec.kt

@@ -39,6 +39,18 @@ abstract class HybridNativeListSpec: HybridView() {
   @set:Keep
   abstract var containerSlotHeightsJson: String
   
+  @get:DoNotStrip
+  @get:Keep
+  @set:DoNotStrip
+  @set:Keep
+  abstract var topScrollEdgeHard: Boolean
+  
+  @get:DoNotStrip
+  @get:Keep
+  @set:DoNotStrip
+  @set:Keep
+  abstract var topOverlayHeight: Double
+  
   @get:DoNotStrip
   @get:Keep
   @set:DoNotStrip

package/lib/nitrogen/generated/ios/c++/HybridNativeListSpecSwift.hpp

@@ -86,6 +86,18 @@ namespace margelo::nitro::nativelist {
     inline void setContainerSlotHeightsJson(const std::string& containerSlotHeightsJson) noexcept override {
       _swiftPart.setContainerSlotHeightsJson(containerSlotHeightsJson);
     }
+    inline bool getTopScrollEdgeHard() noexcept override {
+      return _swiftPart.getTopScrollEdgeHard();
+    }
+    inline void setTopScrollEdgeHard(bool topScrollEdgeHard) noexcept override {
+      _swiftPart.setTopScrollEdgeHard(std::forward<decltype(topScrollEdgeHard)>(topScrollEdgeHard));
+    }
+    inline double getTopOverlayHeight() noexcept override {
+      return _swiftPart.getTopOverlayHeight();
+    }
+    inline void setTopOverlayHeight(double topOverlayHeight) noexcept override {
+      _swiftPart.setTopOverlayHeight(std::forward<decltype(topOverlayHeight)>(topOverlayHeight));
+    }
     inline std::string getScrollPositionThresholdsJson() noexcept override {
       auto __result = _swiftPart.getScrollPositionThresholdsJson();
       return __result;

package/lib/nitrogen/generated/ios/c++/views/HybridNativeListComponent.mm

@@ -124,6 +124,18 @@ using namespace margelo::nitro::nativelist::views;
           : !newViewProps.containerSlotHeightsJson.hasSameValue(oldViewProps->containerSlotHeightsJson)) {
       swiftPart.setContainerSlotHeightsJson(newViewProps.containerSlotHeightsJson.get());
     }
+    // topScrollEdgeHard: boolean
+    if (oldViewProps == nullptr
+          ? newViewProps.topScrollEdgeHard.isProvided()
+          : !newViewProps.topScrollEdgeHard.hasSameValue(oldViewProps->topScrollEdgeHard)) {
+      swiftPart.setTopScrollEdgeHard(newViewProps.topScrollEdgeHard.get());
+    }
+    // topOverlayHeight: number
+    if (oldViewProps == nullptr
+          ? newViewProps.topOverlayHeight.isProvided()
+          : !newViewProps.topOverlayHeight.hasSameValue(oldViewProps->topOverlayHeight)) {
+      swiftPart.setTopOverlayHeight(newViewProps.topOverlayHeight.get());
+    }
     // scrollPositionThresholdsJson: string
     if (oldViewProps == nullptr
           ? newViewProps.scrollPositionThresholdsJson.isProvided()

package/lib/nitrogen/generated/ios/swift/HybridNativeListSpec.swift

@@ -12,6 +12,8 @@ public protocol HybridNativeListSpec_protocol: HybridObject, HybridView {
   // Properties
   var snapshotJson: String { get set }
   var containerSlotHeightsJson: String { get set }
+  var topScrollEdgeHard: Bool { get set }
+  var topOverlayHeight: Double { get set }
   var scrollPositionThresholdsJson: String { get set }
   var onScrollPositionThresholdChange: ((_ isBeyondThreshold: Bool) -> Void)? { get set }
   var keyboardDismissMode: NativeListKeyboardDismissMode { get set }

package/lib/nitrogen/generated/ios/swift/HybridNativeListSpec_cxx.swift

@@ -143,6 +143,28 @@ open class HybridNativeListSpec_cxx {
     }
   }
   
+  public final var topScrollEdgeHard: Bool {
+    @inline(__always)
+    get {
+      return self.__implementation.topScrollEdgeHard
+    }
+    @inline(__always)
+    set {
+      self.__implementation.topScrollEdgeHard = newValue
+    }
+  }
+  
+  public final var topOverlayHeight: Double {
+    @inline(__always)
+    get {
+      return self.__implementation.topOverlayHeight
+    }
+    @inline(__always)
+    set {
+      self.__implementation.topOverlayHeight = newValue
+    }
+  }
+  
   public final var scrollPositionThresholdsJson: std.string {
     @inline(__always)
     get {

package/lib/nitrogen/generated/shared/c++/HybridNativeListSpec.cpp

@@ -18,6 +18,10 @@ namespace margelo::nitro::nativelist {
       prototype.registerHybridSetter("snapshotJson", &HybridNativeListSpec::setSnapshotJson);
       prototype.registerHybridGetter("containerSlotHeightsJson", &HybridNativeListSpec::getContainerSlotHeightsJson);
       prototype.registerHybridSetter("containerSlotHeightsJson", &HybridNativeListSpec::setContainerSlotHeightsJson);
+      prototype.registerHybridGetter("topScrollEdgeHard", &HybridNativeListSpec::getTopScrollEdgeHard);
+      prototype.registerHybridSetter("topScrollEdgeHard", &HybridNativeListSpec::setTopScrollEdgeHard);
+      prototype.registerHybridGetter("topOverlayHeight", &HybridNativeListSpec::getTopOverlayHeight);
+      prototype.registerHybridSetter("topOverlayHeight", &HybridNativeListSpec::setTopOverlayHeight);
       prototype.registerHybridGetter("scrollPositionThresholdsJson", &HybridNativeListSpec::getScrollPositionThresholdsJson);
       prototype.registerHybridSetter("scrollPositionThresholdsJson", &HybridNativeListSpec::setScrollPositionThresholdsJson);
       prototype.registerHybridGetter("onScrollPositionThresholdChange", &HybridNativeListSpec::getOnScrollPositionThresholdChange);

package/lib/nitrogen/generated/shared/c++/HybridNativeListSpec.hpp

@@ -58,6 +58,10 @@ namespace margelo::nitro::nativelist {
       virtual void setSnapshotJson(const std::string& snapshotJson) = 0;
       virtual std::string getContainerSlotHeightsJson() = 0;
       virtual void setContainerSlotHeightsJson(const std::string& containerSlotHeightsJson) = 0;
+      virtual bool getTopScrollEdgeHard() = 0;
+      virtual void setTopScrollEdgeHard(bool topScrollEdgeHard) = 0;
+      virtual double getTopOverlayHeight() = 0;
+      virtual void setTopOverlayHeight(double topOverlayHeight) = 0;
       virtual std::string getScrollPositionThresholdsJson() = 0;
       virtual void setScrollPositionThresholdsJson(const std::string& scrollPositionThresholdsJson) = 0;
       virtual std::optional<std::function<void(bool /* isBeyondThreshold */)>> getOnScrollPositionThresholdChange() = 0;

package/lib/nitrogen/generated/shared/c++/views/HybridNativeListComponent.cpp

@@ -22,6 +22,8 @@ namespace margelo::nitro::nativelist::views {
     react::ViewProps(context, sourceProps, rawProps, filterObjectKeys),
     snapshotJson(nitro::ReactProp<std::string>::fromRawValue("NativeList", "snapshotJson", rawProps, sourceProps.snapshotJson)),
     containerSlotHeightsJson(nitro::ReactProp<std::string>::fromRawValue("NativeList", "containerSlotHeightsJson", rawProps, sourceProps.containerSlotHeightsJson)),
+    topScrollEdgeHard(nitro::ReactProp<bool>::fromRawValue("NativeList", "topScrollEdgeHard", rawProps, sourceProps.topScrollEdgeHard)),
+    topOverlayHeight(nitro::ReactProp<double>::fromRawValue("NativeList", "topOverlayHeight", rawProps, sourceProps.topOverlayHeight)),
     scrollPositionThresholdsJson(nitro::ReactProp<std::string>::fromRawValue("NativeList", "scrollPositionThresholdsJson", rawProps, sourceProps.scrollPositionThresholdsJson)),
     onScrollPositionThresholdChange(nitro::ReactProp<std::optional<std::function<void(bool /* isBeyondThreshold */)>>>::fromRawValue("NativeList", "onScrollPositionThresholdChange", rawProps, sourceProps.onScrollPositionThresholdChange)),
     keyboardDismissMode(nitro::ReactProp<NativeListKeyboardDismissMode>::fromRawValue("NativeList", "keyboardDismissMode", rawProps, sourceProps.keyboardDismissMode)),
@@ -38,6 +40,8 @@ namespace margelo::nitro::nativelist::views {
     switch (hashString(propName)) {
       case hashString("snapshotJson"): return true;
       case hashString("containerSlotHeightsJson"): return true;
+      case hashString("topScrollEdgeHard"): return true;
+      case hashString("topOverlayHeight"): return true;
       case hashString("scrollPositionThresholdsJson"): return true;
       case hashString("onScrollPositionThresholdChange"): return true;
       case hashString("keyboardDismissMode"): return true;

package/lib/nitrogen/generated/shared/c++/views/HybridNativeListComponent.hpp

@@ -47,6 +47,8 @@ namespace margelo::nitro::nativelist::views {
   public:
     nitro::ReactProp<std::string> snapshotJson;
     nitro::ReactProp<std::string> containerSlotHeightsJson;
+    nitro::ReactProp<bool> topScrollEdgeHard;
+    nitro::ReactProp<double> topOverlayHeight;
     nitro::ReactProp<std::string> scrollPositionThresholdsJson;
     nitro::ReactProp<std::optional<std::function<void(bool /* isBeyondThreshold */)>>> onScrollPositionThresholdChange;
     nitro::ReactProp<NativeListKeyboardDismissMode> keyboardDismissMode;
@@ -63,6 +65,8 @@ namespace margelo::nitro::nativelist::views {
     bool hasSameProps(const HybridNativeListProps& other) const noexcept {
       return snapshotJson.hasSameValue(other.snapshotJson) &&
              containerSlotHeightsJson.hasSameValue(other.containerSlotHeightsJson) &&
+             topScrollEdgeHard.hasSameValue(other.topScrollEdgeHard) &&
+             topOverlayHeight.hasSameValue(other.topOverlayHeight) &&
              scrollPositionThresholdsJson.hasSameValue(other.scrollPositionThresholdsJson) &&
              onScrollPositionThresholdChange.hasSameValue(other.onScrollPositionThresholdChange) &&
              keyboardDismissMode.hasSameValue(other.keyboardDismissMode) &&
@@ -80,6 +84,8 @@ namespace margelo::nitro::nativelist::views {
     bool hasAnyProvidedProps() const noexcept {
       return snapshotJson.isProvided() ||
              containerSlotHeightsJson.isProvided() ||
+             topScrollEdgeHard.isProvided() ||
+             topOverlayHeight.isProvided() ||
              scrollPositionThresholdsJson.isProvided() ||
              onScrollPositionThresholdChange.isProvided() ||
              keyboardDismissMode.isProvided() ||

package/lib/nitrogen/generated/shared/json/NativeListConfig.json

@@ -6,6 +6,8 @@
   "validAttributes": {
     "snapshotJson": true,
     "containerSlotHeightsJson": true,
+    "topScrollEdgeHard": true,
+    "topOverlayHeight": true,
     "scrollPositionThresholdsJson": true,
     "onScrollPositionThresholdChange": true,
     "keyboardDismissMode": true,

package/lib/typescript/src/NativeList.nitro.d.ts

@@ -7,6 +7,8 @@ import type { HybridView, HybridViewMethods, HybridViewProps } from 'react-nativ
 export interface NativeListNativeProps extends HybridViewProps {
     snapshotJson: string;
     containerSlotHeightsJson: string;
+    topScrollEdgeHard: boolean;
+    topOverlayHeight: number;
     scrollPositionThresholdsJson: string;
     onScrollPositionThresholdChange?: (isBeyondThreshold: boolean) => void;
     keyboardDismissMode: NativeListKeyboardDismissMode;

package/lib/typescript/src/NativeList.types.d.ts

@@ -79,6 +79,10 @@ export type NativeListProps = Omit<ViewProps, 'children'> & Readonly<{
     listHeader?: ReactNode;
     listFooter?: ReactNode;
     listEmpty?: ReactNode;
+    /** Fixed overlay above scrolling rows on iOS 26 and newer. */
+    topOverlay?: ReactNode;
+    /** Enables UIKit's hard top scroll-edge effect on iOS 26 and newer. */
+    topScrollEdgeEffect?: 'hard';
     /** Web only. Defaults to true and is ignored by the native host. */
     webVirtualizationEnabled?: boolean;
     /** Web only. Hosts the section index inside this container. */

package/nitrogen/generated/android/c++/JHybridNativeListSpec.cpp

@@ -75,6 +75,24 @@ namespace margelo::nitro::nativelist {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<jni::JString> /* containerSlotHeightsJson */)>("setContainerSlotHeightsJson");
     method(_javaPart, jni::make_jstring(containerSlotHeightsJson));
   }
+  bool JHybridNativeListSpec::getTopScrollEdgeHard() {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jboolean()>("getTopScrollEdgeHard");
+    auto __result = method(_javaPart);
+    return static_cast<bool>(__result);
+  }
+  void JHybridNativeListSpec::setTopScrollEdgeHard(bool topScrollEdgeHard) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(jboolean /* topScrollEdgeHard */)>("setTopScrollEdgeHard");
+    method(_javaPart, topScrollEdgeHard);
+  }
+  double JHybridNativeListSpec::getTopOverlayHeight() {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<double()>("getTopOverlayHeight");
+    auto __result = method(_javaPart);
+    return __result;
+  }
+  void JHybridNativeListSpec::setTopOverlayHeight(double topOverlayHeight) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(double /* topOverlayHeight */)>("setTopOverlayHeight");
+    method(_javaPart, topOverlayHeight);
+  }
   std::string JHybridNativeListSpec::getScrollPositionThresholdsJson() {
     static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<jni::JString>()>("getScrollPositionThresholdsJson");
     auto __result = method(_javaPart);

package/nitrogen/generated/android/c++/JHybridNativeListSpec.hpp

@@ -54,6 +54,10 @@ namespace margelo::nitro::nativelist {
     void setSnapshotJson(const std::string& snapshotJson) override;
     std::string getContainerSlotHeightsJson() override;
     void setContainerSlotHeightsJson(const std::string& containerSlotHeightsJson) override;
+    bool getTopScrollEdgeHard() override;
+    void setTopScrollEdgeHard(bool topScrollEdgeHard) override;
+    double getTopOverlayHeight() override;
+    void setTopOverlayHeight(double topOverlayHeight) override;
     std::string getScrollPositionThresholdsJson() override;
     void setScrollPositionThresholdsJson(const std::string& scrollPositionThresholdsJson) override;
     std::optional<std::function<void(bool /* isBeyondThreshold */)>> getOnScrollPositionThresholdChange() override;

package/nitrogen/generated/android/c++/views/JHybridNativeListStateUpdater.cpp

@@ -63,6 +63,16 @@ void JHybridNativeListStateUpdater::updateViewProps(jni::alias_ref<jni::JClass>
         : !newProps->containerSlotHeightsJson.hasSameValue(oldProps->containerSlotHeightsJson)) {
     hybridView->setContainerSlotHeightsJson(newProps->containerSlotHeightsJson.get());
   }
+  if (oldProps == nullptr
+        ? newProps->topScrollEdgeHard.isProvided()
+        : !newProps->topScrollEdgeHard.hasSameValue(oldProps->topScrollEdgeHard)) {
+    hybridView->setTopScrollEdgeHard(newProps->topScrollEdgeHard.get());
+  }
+  if (oldProps == nullptr
+        ? newProps->topOverlayHeight.isProvided()
+        : !newProps->topOverlayHeight.hasSameValue(oldProps->topOverlayHeight)) {
+    hybridView->setTopOverlayHeight(newProps->topOverlayHeight.get());
+  }
   if (oldProps == nullptr
         ? newProps->scrollPositionThresholdsJson.isProvided()
         : !newProps->scrollPositionThresholdsJson.hasSameValue(oldProps->scrollPositionThresholdsJson)) {

package/nitrogen/generated/android/kotlin/com/margelo/nitro/nativelist/HybridNativeListSpec.kt

@@ -39,6 +39,18 @@ abstract class HybridNativeListSpec: HybridView() {
   @set:Keep
   abstract var containerSlotHeightsJson: String
   
+  @get:DoNotStrip
+  @get:Keep
+  @set:DoNotStrip
+  @set:Keep
+  abstract var topScrollEdgeHard: Boolean
+  
+  @get:DoNotStrip
+  @get:Keep
+  @set:DoNotStrip
+  @set:Keep
+  abstract var topOverlayHeight: Double
+  
   @get:DoNotStrip
   @get:Keep
   @set:DoNotStrip

package/nitrogen/generated/ios/c++/HybridNativeListSpecSwift.hpp

@@ -86,6 +86,18 @@ namespace margelo::nitro::nativelist {
     inline void setContainerSlotHeightsJson(const std::string& containerSlotHeightsJson) noexcept override {
       _swiftPart.setContainerSlotHeightsJson(containerSlotHeightsJson);
     }
+    inline bool getTopScrollEdgeHard() noexcept override {
+      return _swiftPart.getTopScrollEdgeHard();
+    }
+    inline void setTopScrollEdgeHard(bool topScrollEdgeHard) noexcept override {
+      _swiftPart.setTopScrollEdgeHard(std::forward<decltype(topScrollEdgeHard)>(topScrollEdgeHard));
+    }
+    inline double getTopOverlayHeight() noexcept override {
+      return _swiftPart.getTopOverlayHeight();
+    }
+    inline void setTopOverlayHeight(double topOverlayHeight) noexcept override {
+      _swiftPart.setTopOverlayHeight(std::forward<decltype(topOverlayHeight)>(topOverlayHeight));
+    }
     inline std::string getScrollPositionThresholdsJson() noexcept override {
       auto __result = _swiftPart.getScrollPositionThresholdsJson();
       return __result;

package/nitrogen/generated/ios/c++/views/HybridNativeListComponent.mm

@@ -124,6 +124,18 @@ using namespace margelo::nitro::nativelist::views;
           : !newViewProps.containerSlotHeightsJson.hasSameValue(oldViewProps->containerSlotHeightsJson)) {
       swiftPart.setContainerSlotHeightsJson(newViewProps.containerSlotHeightsJson.get());
     }
+    // topScrollEdgeHard: boolean
+    if (oldViewProps == nullptr
+          ? newViewProps.topScrollEdgeHard.isProvided()
+          : !newViewProps.topScrollEdgeHard.hasSameValue(oldViewProps->topScrollEdgeHard)) {
+      swiftPart.setTopScrollEdgeHard(newViewProps.topScrollEdgeHard.get());
+    }
+    // topOverlayHeight: number
+    if (oldViewProps == nullptr
+          ? newViewProps.topOverlayHeight.isProvided()
+          : !newViewProps.topOverlayHeight.hasSameValue(oldViewProps->topOverlayHeight)) {
+      swiftPart.setTopOverlayHeight(newViewProps.topOverlayHeight.get());
+    }
     // scrollPositionThresholdsJson: string
     if (oldViewProps == nullptr
           ? newViewProps.scrollPositionThresholdsJson.isProvided()

package/nitrogen/generated/ios/swift/HybridNativeListSpec.swift

@@ -12,6 +12,8 @@ public protocol HybridNativeListSpec_protocol: HybridObject, HybridView {
   // Properties
   var snapshotJson: String { get set }
   var containerSlotHeightsJson: String { get set }
+  var topScrollEdgeHard: Bool { get set }
+  var topOverlayHeight: Double { get set }
   var scrollPositionThresholdsJson: String { get set }
   var onScrollPositionThresholdChange: ((_ isBeyondThreshold: Bool) -> Void)? { get set }
   var keyboardDismissMode: NativeListKeyboardDismissMode { get set }

package/nitrogen/generated/ios/swift/HybridNativeListSpec_cxx.swift

@@ -143,6 +143,28 @@ open class HybridNativeListSpec_cxx {
     }
   }
   
+  public final var topScrollEdgeHard: Bool {
+    @inline(__always)
+    get {
+      return self.__implementation.topScrollEdgeHard
+    }
+    @inline(__always)
+    set {
+      self.__implementation.topScrollEdgeHard = newValue
+    }
+  }
+  
+  public final var topOverlayHeight: Double {
+    @inline(__always)
+    get {
+      return self.__implementation.topOverlayHeight
+    }
+    @inline(__always)
+    set {
+      self.__implementation.topOverlayHeight = newValue
+    }
+  }
+  
   public final var scrollPositionThresholdsJson: std.string {
     @inline(__always)
     get {

package/nitrogen/generated/shared/c++/HybridNativeListSpec.cpp

@@ -18,6 +18,10 @@ namespace margelo::nitro::nativelist {
       prototype.registerHybridSetter("snapshotJson", &HybridNativeListSpec::setSnapshotJson);
       prototype.registerHybridGetter("containerSlotHeightsJson", &HybridNativeListSpec::getContainerSlotHeightsJson);
       prototype.registerHybridSetter("containerSlotHeightsJson", &HybridNativeListSpec::setContainerSlotHeightsJson);
+      prototype.registerHybridGetter("topScrollEdgeHard", &HybridNativeListSpec::getTopScrollEdgeHard);
+      prototype.registerHybridSetter("topScrollEdgeHard", &HybridNativeListSpec::setTopScrollEdgeHard);
+      prototype.registerHybridGetter("topOverlayHeight", &HybridNativeListSpec::getTopOverlayHeight);
+      prototype.registerHybridSetter("topOverlayHeight", &HybridNativeListSpec::setTopOverlayHeight);
       prototype.registerHybridGetter("scrollPositionThresholdsJson", &HybridNativeListSpec::getScrollPositionThresholdsJson);
       prototype.registerHybridSetter("scrollPositionThresholdsJson", &HybridNativeListSpec::setScrollPositionThresholdsJson);
       prototype.registerHybridGetter("onScrollPositionThresholdChange", &HybridNativeListSpec::getOnScrollPositionThresholdChange);

package/nitrogen/generated/shared/c++/HybridNativeListSpec.hpp

@@ -58,6 +58,10 @@ namespace margelo::nitro::nativelist {
       virtual void setSnapshotJson(const std::string& snapshotJson) = 0;
       virtual std::string getContainerSlotHeightsJson() = 0;
       virtual void setContainerSlotHeightsJson(const std::string& containerSlotHeightsJson) = 0;
+      virtual bool getTopScrollEdgeHard() = 0;
+      virtual void setTopScrollEdgeHard(bool topScrollEdgeHard) = 0;
+      virtual double getTopOverlayHeight() = 0;
+      virtual void setTopOverlayHeight(double topOverlayHeight) = 0;
       virtual std::string getScrollPositionThresholdsJson() = 0;
       virtual void setScrollPositionThresholdsJson(const std::string& scrollPositionThresholdsJson) = 0;
       virtual std::optional<std::function<void(bool /* isBeyondThreshold */)>> getOnScrollPositionThresholdChange() = 0;

package/nitrogen/generated/shared/c++/views/HybridNativeListComponent.cpp

@@ -22,6 +22,8 @@ namespace margelo::nitro::nativelist::views {
     react::ViewProps(context, sourceProps, rawProps, filterObjectKeys),
     snapshotJson(nitro::ReactProp<std::string>::fromRawValue("NativeList", "snapshotJson", rawProps, sourceProps.snapshotJson)),
     containerSlotHeightsJson(nitro::ReactProp<std::string>::fromRawValue("NativeList", "containerSlotHeightsJson", rawProps, sourceProps.containerSlotHeightsJson)),
+    topScrollEdgeHard(nitro::ReactProp<bool>::fromRawValue("NativeList", "topScrollEdgeHard", rawProps, sourceProps.topScrollEdgeHard)),
+    topOverlayHeight(nitro::ReactProp<double>::fromRawValue("NativeList", "topOverlayHeight", rawProps, sourceProps.topOverlayHeight)),
     scrollPositionThresholdsJson(nitro::ReactProp<std::string>::fromRawValue("NativeList", "scrollPositionThresholdsJson", rawProps, sourceProps.scrollPositionThresholdsJson)),
     onScrollPositionThresholdChange(nitro::ReactProp<std::optional<std::function<void(bool /* isBeyondThreshold */)>>>::fromRawValue("NativeList", "onScrollPositionThresholdChange", rawProps, sourceProps.onScrollPositionThresholdChange)),
     keyboardDismissMode(nitro::ReactProp<NativeListKeyboardDismissMode>::fromRawValue("NativeList", "keyboardDismissMode", rawProps, sourceProps.keyboardDismissMode)),
@@ -38,6 +40,8 @@ namespace margelo::nitro::nativelist::views {
     switch (hashString(propName)) {
       case hashString("snapshotJson"): return true;
       case hashString("containerSlotHeightsJson"): return true;
+      case hashString("topScrollEdgeHard"): return true;
+      case hashString("topOverlayHeight"): return true;
       case hashString("scrollPositionThresholdsJson"): return true;
       case hashString("onScrollPositionThresholdChange"): return true;
       case hashString("keyboardDismissMode"): return true;

package/nitrogen/generated/shared/c++/views/HybridNativeListComponent.hpp

@@ -47,6 +47,8 @@ namespace margelo::nitro::nativelist::views {
   public:
     nitro::ReactProp<std::string> snapshotJson;
     nitro::ReactProp<std::string> containerSlotHeightsJson;
+    nitro::ReactProp<bool> topScrollEdgeHard;
+    nitro::ReactProp<double> topOverlayHeight;
     nitro::ReactProp<std::string> scrollPositionThresholdsJson;
     nitro::ReactProp<std::optional<std::function<void(bool /* isBeyondThreshold */)>>> onScrollPositionThresholdChange;
     nitro::ReactProp<NativeListKeyboardDismissMode> keyboardDismissMode;
@@ -63,6 +65,8 @@ namespace margelo::nitro::nativelist::views {
     bool hasSameProps(const HybridNativeListProps& other) const noexcept {
       return snapshotJson.hasSameValue(other.snapshotJson) &&
              containerSlotHeightsJson.hasSameValue(other.containerSlotHeightsJson) &&
+             topScrollEdgeHard.hasSameValue(other.topScrollEdgeHard) &&
+             topOverlayHeight.hasSameValue(other.topOverlayHeight) &&
              scrollPositionThresholdsJson.hasSameValue(other.scrollPositionThresholdsJson) &&
              onScrollPositionThresholdChange.hasSameValue(other.onScrollPositionThresholdChange) &&
              keyboardDismissMode.hasSameValue(other.keyboardDismissMode) &&
@@ -80,6 +84,8 @@ namespace margelo::nitro::nativelist::views {
     bool hasAnyProvidedProps() const noexcept {
       return snapshotJson.isProvided() ||
              containerSlotHeightsJson.isProvided() ||
+             topScrollEdgeHard.isProvided() ||
+             topOverlayHeight.isProvided() ||
              scrollPositionThresholdsJson.isProvided() ||
              onScrollPositionThresholdChange.isProvided() ||
              keyboardDismissMode.isProvided() ||

package/nitrogen/generated/shared/json/NativeListConfig.json

@@ -6,6 +6,8 @@
   "validAttributes": {
     "snapshotJson": true,
     "containerSlotHeightsJson": true,
+    "topScrollEdgeHard": true,
+    "topOverlayHeight": true,
     "scrollPositionThresholdsJson": true,
     "onScrollPositionThresholdChange": true,
     "keyboardDismissMode": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-native-list",
-  "version": "3.0.177",
+  "version": "3.0.179-alpha.20261015",
   "description": "Template-driven native RecyclerView and UICollectionView for React Native",
   "source": "./src/index.ts",
   "main": "./lib/module/index.js",
@@ -87,8 +87,8 @@
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "@onekeyfe/react-native-image": "3.0.177",
-    "@onekeyfe/react-native-native-logger": "3.0.177",
+    "@onekeyfe/react-native-image": "3.0.179-alpha.20261015",
+    "@onekeyfe/react-native-native-logger": "3.0.179-alpha.20261015",
     "react": "*",
     "react-native": "*",
     "react-native-nitro-modules": "0.37.0"

package/src/NativeList.nitro.ts

@@ -12,6 +12,8 @@ import type {
 export interface NativeListNativeProps extends HybridViewProps {
   snapshotJson: string;
   containerSlotHeightsJson: string;
+  topScrollEdgeHard: boolean;
+  topOverlayHeight: number;
   scrollPositionThresholdsJson: string;
   onScrollPositionThresholdChange?: (isBeyondThreshold: boolean) => void;
   keyboardDismissMode: NativeListKeyboardDismissMode;

package/src/NativeList.tsx

@@ -14,7 +14,7 @@ import {
   NativeAvatarPrefetchModel,
   NativeAvatarPrefetchQueue,
 } from './avatarPrefetch';
-import { View } from 'react-native';
+import { Platform, View } from 'react-native';
 import { callback, getHostComponent } from 'react-native-nitro-modules';
 import type {
   NativeListMethods,
@@ -101,6 +101,8 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
       listHeader,
       listFooter,
       listEmpty,
+      topOverlay,
+      topScrollEdgeEffect,
       scrollPositionThresholds,
       webVirtualizationEnabled: _webVirtualizationEnabled,
       webSectionIndexContainerRef: _webSectionIndexContainerRef,
@@ -124,6 +126,12 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
     forwardedRef
   ) {
     const [slotHeights, setSlotHeights] = useState([0, 0, 0]);
+    const [topOverlayHeight, setTopOverlayHeight] = useState(0);
+    const hasTopOverlay =
+      Platform?.OS === 'ios' &&
+      Number(Platform.Version) >= 26 &&
+      topScrollEdgeEffect === 'hard' &&
+      topOverlay != null;
     const containerSlotHeightsJson = JSON.stringify(slotHeights);
     const slotInset =
       snapshot.layout.contentPaddingHorizontal ??
@@ -506,6 +514,8 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
         {...nativeCallbacks}
         snapshotJson={snapshotJson}
         containerSlotHeightsJson={containerSlotHeightsJson}
+        topScrollEdgeHard={hasTopOverlay}
+        topOverlayHeight={hasTopOverlay ? topOverlayHeight : 0}
         scrollPositionThresholdsJson={scrollPositionThresholdsJson}
         keyboardDismissMode={keyboardDismissMode}
         keyboardShouldPersistTaps={normalizedKeyboardShouldPersistTaps}
@@ -534,6 +544,20 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
             {content}
           </View>
         ))}
+        {hasTopOverlay ? (
+          <View
+            collapsable={false}
+            style={{ position: 'absolute', top: 0, left: 0, right: 0 }}
+            onLayout={(event) => {
+              const height = Math.ceil(event.nativeEvent.layout.height);
+              setTopOverlayHeight((previous) =>
+                previous === height ? previous : height
+              );
+            }}
+          >
+            {topOverlay}
+          </View>
+        ) : null}
       </NativeListHost>
     );
   }

package/src/NativeList.types.ts

@@ -123,6 +123,10 @@ export type NativeListProps = Omit<ViewProps, 'children'> &
     listHeader?: ReactNode;
     listFooter?: ReactNode;
     listEmpty?: ReactNode;
+    /** Fixed overlay above scrolling rows on iOS 26 and newer. */
+    topOverlay?: ReactNode;
+    /** Enables UIKit's hard top scroll-edge effect on iOS 26 and newer. */
+    topScrollEdgeEffect?: 'hard';
     /** Web only. Defaults to true and is ignored by the native host. */
     webVirtualizationEnabled?: boolean;
     /** Web only. Hosts the section index inside this container. */

package/src/NativeList.web.tsx

@@ -85,6 +85,8 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
       listHeader: _listHeader,
       listEmpty: _listEmpty,
       listFooter: _listFooter,
+      topOverlay: _topOverlay,
+      topScrollEdgeEffect: _topScrollEdgeEffect,
       scrollPositionThresholds: _scrollPositionThresholds,
       onScrollPositionThresholdChange: _onScrollPositionThresholdChange,
       webVirtualizationEnabled = true,