@swmansion/react-native-bottom-sheet 0.10.2 → 0.11.0

package/README.md

@@ -18,6 +18,47 @@ React Native.
 - Programmatic‍-‍only detents for snap points unreachable
   by dragging.
 
+## How it compares
+
+React Native already has strong bottom‍-‍sheet options, but they make
+different tradeoffs. React Native Bottom Sheet gives you composable React Native
+primitives backed by native sheet mechanics: You compose the surface in React,
+while the sheet host, gestures, snapping, and scroll negotiation run in
+native code.
+
+[`@gorhom/bottom-sheet`](https://gorhom.dev/react-native-bottom-sheet) is the
+closest match in day‍-‍to‍-‍day functionality: configurable
+detents, dynamic sizing, scrollable coordination, inline sheets, and modal
+presentation. The main difference is the implementation model. React Native
+Bottom Sheet moves the sheet host, gestures, snapping, and scroll negotiation
+into native code, so heavy React rendering and busy JS work are less likely to
+affect drag and snap performance. It also does not require Reanimated or React
+Native Gesture Handler. Because scroll coordination is native, regular React
+Native scrollables work inside the sheet without
+bottom‍-‍sheet‍-‍specific list components or wrapper factories.
+
+[Expo UI](https://docs.expo.dev/versions/latest/sdk/ui) sheets,
+[Expo Router form sheets](https://docs.expo.dev/router/advanced/modals/#form-sheet),
+and native modal‍-‍sheet libraries such as
+[True Sheet](https://sheet.lodev09.com) lean into platform presentation APIs.
+That is a good fit when you want a system‍-‍style presented sheet, but
+it also means the platform and presentation system decide more of the behavior.
+React Native Bottom Sheet is built as a lower‍-‍level sheet primitive
+instead: The same native implementation powers both persistent inline sheets and
+modal sheets, you provide the complete sheet surface in React, and detents can
+include app‍-‍level behavior such as programmatic‍-‍only
+snap points.
+
+That difference also matters for layering. A platform‍-‍presented sheet
+can disable dimming and allow background interaction, but it is still drawn as a
+presented native sheet over the React Native view hierarchy. `BottomSheet` is
+actually inline: It renders in your screen’s React Native hierarchy and can be
+layered alongside nearby content. When you do need a modal, `ModalBottomSheet`
+is rendered through `BottomSheetProvider`’s portal rather than through a
+separate native window, so global UI such as toasts, menus, floating controls,
+or debug overlays can be arranged above or below it by where you place them
+relative to the provider.
+
 ## Getting started
 
 1. Install React Native Bottom Sheet:
@@ -29,7 +70,7 @@ React Native.
 2. Ensure the peer dependency is installed:
 
    ```sh
-   npm i react-native-safe-area-context@^4.0.0
+   npm i react-native-safe-area-context
    ```
 
 3. Wrap your app with `BottomSheetProvider`:
@@ -41,9 +82,9 @@ React Native.
 ## Usage
 
 The library provides two components: `BottomSheet` (inline) and
-`ModalBottomSheet` (modal). Both render their children as the sheet content
-(including any background) and are controlled via `detents`, `index`,
-and `onIndexChange`. Use `onSettle` for
+`ModalBottomSheet` (modal). Both render their children as the sheet content,
+with a `surface` prop for the background behind it, and are controlled via
+`detents`, `index`, and `onIndexChange`. Use `onSettle` for
 post‍-‍snap observability.
 
 ### Inline
@@ -56,14 +97,14 @@ const insets = useSafeAreaInsets();
 ```
 
 ```tsx
-<BottomSheet index={index} onIndexChange={setIndex}>
-  <View
-    style={{
-      backgroundColor: 'white',
-      padding: 16,
-      paddingBottom: insets.bottom + 16,
-    }}
-  >
+<BottomSheet
+  index={index}
+  onIndexChange={setIndex}
+  surface={
+    <View style={[StyleSheet.absoluteFill, { backgroundColor: 'white' }]} />
+  }
+>
+  <View style={{ padding: 16, paddingBottom: insets.bottom + 16 }}>
     <Text>Sheet content</Text>
   </View>
 </BottomSheet>
@@ -80,14 +121,14 @@ const insets = useSafeAreaInsets();
 ```
 
 ```tsx
-<ModalBottomSheet index={index} onIndexChange={setIndex}>
-  <View
-    style={{
-      backgroundColor: 'white',
-      padding: 16,
-      paddingBottom: insets.bottom + 16,
-    }}
-  >
+<ModalBottomSheet
+  index={index}
+  onIndexChange={setIndex}
+  surface={
+    <View style={[StyleSheet.absoluteFill, { backgroundColor: 'white' }]} />
+  }
+>
+  <View style={{ padding: 16, paddingBottom: insets.bottom + 16 }}>
     <Text>Sheet content</Text>
   </View>
 </ModalBottomSheet>
@@ -102,12 +143,39 @@ its&nbsp;color:
 <ModalBottomSheet
   index={index}
   onIndexChange={setIndex}
+  surface={/* ... */}
   scrimColor="rgba(0, 0, 0, 0.3)"
 >
   {/* ... */}
 </ModalBottomSheet>
 ```
 
+### Surface
+
+Provide the sheet’s background through the `surface` prop. The library renders
+it behind your content and sizes it natively to cover the whole sheet,
+independently of the content&nbsp;height.
+
+Decoupling the surface this way keeps the sheet covered as the content height
+changes. When content shrinks, the sheet animates to its new height without the
+background briefly exposing blank space behind the&nbsp;content.
+
+Give the surface a filling style such as `StyleSheet.absoluteFill`. It is
+mounted in a full&zwj;-&zwj;size host, so a surface sized only by its own
+content would collapse and not&nbsp;show.
+
+```tsx
+<BottomSheet // Or `ModalBottomSheet`.
+  index={index}
+  onIndexChange={setIndex}
+  surface={
+    <View style={[StyleSheet.absoluteFill, { backgroundColor: 'white' }]} />
+  }
+>
+  <Text>Sheet content</Text>
+</BottomSheet>
+```
+
 ### Scrollable negotiation
 
 By default, the sheet coordinates vertical gestures with nested scrollables,
@@ -121,6 +189,7 @@ set&nbsp;`disableScrollableNegotiation`:
 <BottomSheet
   index={index}
   onIndexChange={setIndex}
+  surface={/* ... */}
   disableScrollableNegotiation
 >
   {/* ... */}
@@ -134,18 +203,20 @@ Detents are the points to which the sheet snaps. Each detent is either a number
 the available screen height). The default detents are `[0, 'content']`.
 
 Sheet children are laid out in a flex container. For a full&zwj;-&zwj;height
-sheet, apply `flex: 1` to your sheet surface and use the
-`'content'`&nbsp;detent:
+sheet, apply `flex: 1` to your content and use the `'content'`&nbsp;detent.
+`surface` is sized by the library, so `flex: 1` only ever belongs on your
+content, never on the&nbsp;surface:
 
 ```tsx
 <BottomSheet
   // `detents` defaults to `[0, 'content']`.
   index={index}
   onIndexChange={setIndex}
+  surface={
+    <View style={[StyleSheet.absoluteFill, { backgroundColor: 'white' }]} />
+  }
 >
-  <View style={{ flex: 1, backgroundColor: 'white' }}>
-    {/* Full-height sheet content. */}
-  </View>
+  <View style={{ flex: 1 }}>{/* Full-height sheet content. */}</View>
 </BottomSheet>
 ```
 
@@ -168,6 +239,7 @@ const [index, setIndex] = useState(0);
   detents={[0, 300, 'content']} // Collapsed, 300 px, content height.
   index={index}
   onIndexChange={setIndex} // Keep controlled state in sync.
+  surface={/* ... */}
   onSettle={(nextIndex) => {
     if (nextIndex === 0) console.log('Sheet collapsed.');
   }}
@@ -190,6 +262,7 @@ drag snapping but can still be targeted via `index`&nbsp;updates.
   detents={[0, programmatic(300), 'content']}
   index={index}
   onIndexChange={setIndex}
+  surface={/* ... */}
   onSettle={(nextIndex) => {
     console.log(`Settled at ${nextIndex}.`);
   }}
@@ -207,6 +280,7 @@ pixels from the bottom of the screen to the top of the&nbsp;sheet).
 <BottomSheet // Or `ModalBottomSheet`.
   index={index}
   onIndexChange={setIndex}
+  surface={/* ... */}
   onPositionChange={(position) => {
     console.log(position);
   }}
@@ -226,6 +300,7 @@ const position = useSharedValue(0);
 <BottomSheet
   index={index}
   onIndexChange={setIndex}
+  surface={/* ... */}
   onPositionChange={(nextPosition) => {
     position.value = nextPosition;
   }}

package/android/src/main/java/com/swmansion/reactnativebottomsheet/BottomSheetPackage.kt

@@ -10,5 +10,5 @@ class BottomSheetPackage : ReactPackage {
     emptyList()
 
   override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> =
-    listOf(BottomSheetViewManager())
+    listOf(BottomSheetViewManager(), BottomSheetSurfaceViewManager())
 }

package/android/src/main/java/com/swmansion/reactnativebottomsheet/BottomSheetSurfaceView.kt

@@ -0,0 +1,10 @@
+package com.swmansion.reactnativebottomsheet
+
+import android.content.Context
+import com.facebook.react.views.view.ReactViewGroup
+
+// Visual surface that sits behind the sheet content. It carries no behavior of
+// its own; the BottomSheetView identifies it by this type and owns its geometry,
+// laying it out to cover the full sheet so a content shrink never exposes blank
+// space. Its React children provide the appearance only.
+class BottomSheetSurfaceView(context: Context) : ReactViewGroup(context)

package/android/src/main/java/com/swmansion/reactnativebottomsheet/BottomSheetSurfaceViewManager.kt

@@ -0,0 +1,27 @@
+package com.swmansion.reactnativebottomsheet
+
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.ViewGroupManager
+import com.facebook.react.uimanager.ViewManagerDelegate
+import com.facebook.react.viewmanagers.BottomSheetSurfaceViewManagerDelegate
+import com.facebook.react.viewmanagers.BottomSheetSurfaceViewManagerInterface
+
+@ReactModule(name = BottomSheetSurfaceViewManager.NAME)
+class BottomSheetSurfaceViewManager :
+  ViewGroupManager<BottomSheetSurfaceView>(),
+  BottomSheetSurfaceViewManagerInterface<BottomSheetSurfaceView> {
+
+  companion object {
+    const val NAME = "BottomSheetSurfaceView"
+  }
+
+  private val delegate = BottomSheetSurfaceViewManagerDelegate(this)
+
+  override fun getDelegate(): ViewManagerDelegate<BottomSheetSurfaceView> = delegate
+
+  override fun getName(): String = NAME
+
+  override fun createViewInstance(context: ThemedReactContext): BottomSheetSurfaceView =
+    BottomSheetSurfaceView(context)
+}

package/android/src/main/java/com/swmansion/reactnativebottomsheet/BottomSheetView.kt

@@ -88,6 +88,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
   private var scrimPinnedFull = false
   private var maxDetentHeight = Float.NaN
   private var contentHeightMarker: View? = null
+  private var surfaceView: View? = null
 
   private val contentHeightMarkerLayoutListener =
     View.OnLayoutChangeListener { _, _, _, _, _, _, _, _, _ -> refreshDetentsFromLayout() }
@@ -166,7 +167,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
       if (animateIn && isInvalidContentDetentTarget(clampedIndex)) {
         targetIndex = clampedIndex
         pendingIndex = clampedIndex
-        val closedTy = detentSpecs.maxOfOrNull { it.height } ?: h.toFloat()
+        val closedTy = resolvedMaxDetentHeight(h)
         sheetContainer.translationY = closedTy
         emitPosition()
         return
@@ -177,7 +178,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
       targetIndex = clampedIndex
 
       if (animateIn) {
-        val closedTy = detentSpecs.maxOfOrNull { it.height } ?: h.toFloat()
+        val closedTy = resolvedMaxDetentHeight(h)
         sheetContainer.translationY = closedTy
         emitPosition()
         snapToIndex(targetIndex, 0f, emitIndexChange = false, emitSettle = true)
@@ -198,18 +199,25 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
     super.dispatchDraw(canvas)
   }
 
-  private fun layoutSheetChildren() {
+  private fun layoutSheetChildren(containerWidth: Int, containerHeight: Int) {
     for (i in 0 until sheetContainer.childCount) {
       val child = sheetContainer.getChildAt(i)
-      child.layout(0, 0, child.measuredWidth, child.measuredHeight)
+      if (child === surfaceView) {
+        // The surface fills the full container so it always covers the visible
+        // sheet (the container is translated to the current sheet position),
+        // regardless of how short the content becomes.
+        child.layout(0, 0, containerWidth, containerHeight)
+      } else {
+        child.layout(0, 0, child.measuredWidth, child.measuredHeight)
+      }
     }
   }
 
   private fun layoutSheetContainer(viewWidth: Int, viewHeight: Int) {
-    val maxHeight = detentSpecs.maxOfOrNull { it.height } ?: resolvedMaxDetentHeight(viewHeight)
+    val maxHeight = resolvedMaxDetentHeight(viewHeight)
     val containerTop = (viewHeight - maxHeight).toInt()
     sheetContainer.layout(0, containerTop, viewWidth, containerTop + maxHeight.toInt())
-    layoutSheetChildren()
+    layoutSheetChildren(viewWidth, maxHeight.toInt())
   }
 
   // MARK: - Prop setters
@@ -252,6 +260,12 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
     refreshDetentsFromLayout()
   }
 
+  // Stable coordinate base for the sheet container. The container is sized to
+  // the full available height rather than the tallest detent, so it stays a
+  // fixed-size canvas: when content — and thus the `content` detent — shrinks,
+  // the container does not collapse underneath the sheet, leaving room to
+  // animate the sheet down to its new height. The surface fills this canvas, so
+  // the area below the shrunken content stays covered throughout.
   private fun resolvedMaxDetentHeight(viewHeight: Int = height): Float {
     val viewHeightPx = viewHeight.toFloat()
     if (!maxDetentHeight.isFinite() || maxDetentHeight <= 0f) {
@@ -294,7 +308,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
       return
     }
 
-    val previousMaxHeight = detentSpecs.maxOfOrNull { it.height } ?: resolvedMaxDetentHeight()
+    val previousMaxHeight = resolvedMaxDetentHeight()
     // Whether the scrim is currently fully opaque, i.e. the sheet is settled at
     // or above the first non-zero detent. If so, a detent resize must not dip
     // the scrim while the sheet re-anchors to the new geometry.
@@ -308,7 +322,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
 
       if (hasLaidOut && !isPanning) {
         targetIndex = targetIndex.coerceIn(0, detentSpecs.size - 1)
-        val newMaxHeight = detentSpecs.maxOfOrNull { it.height } ?: resolvedMaxDetentHeight()
+        val newMaxHeight = resolvedMaxDetentHeight()
         val targetTy = translationY(targetIndex)
         if (activeAnimation != null && isTargetingClosedDetent) {
           suppressScrimForClosingTarget = true
@@ -337,20 +351,15 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
         } else {
           val currentVisibleHeight = previousMaxHeight - sheetContainer.translationY
           val targetHeight = detentSpecs.getOrNull(targetIndex)?.height ?: 0f
-          val isContentDetent = rawDetentSpecs.getOrNull(targetIndex)?.kind == DetentKind.CONTENT
-          val didShrink = targetHeight < currentVisibleHeight - 0.5f
-          if (isContentDetent && didShrink) {
-            // Content shrank: snap immediately. Animating here would expose
-            // blank space below the shrunken content.
-            sheetContainer.translationY = targetTy
-            emitPosition()
-          } else if (kotlin.math.abs(targetHeight - currentVisibleHeight) <= 0.5f) {
+          if (kotlin.math.abs(targetHeight - currentVisibleHeight) <= 0.5f) {
             // No meaningful change.
             sheetContainer.translationY = targetTy
             emitPosition()
           } else {
-            // Detent value changed (or content grew): re-anchor at the current
-            // visible height, then animate to the new target.
+            // The content detent changed (grew or shrank): re-anchor at the
+            // current visible height, then animate to the new target. The
+            // surface covers the full sheet, so a shrink no longer exposes
+            // blank space.
             sheetContainer.translationY =
               (newMaxHeight - currentVisibleHeight).coerceIn(0f, newMaxHeight)
             scrimPinnedFull = scrimPinnedFull || wasScrimFull
@@ -386,6 +395,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
   }
 
   private fun refreshContentHeightMarker() {
+    surfaceView = findSurfaceView()
     val marker = findContentHeightMarker()
     if (marker === contentHeightMarker) return
     contentHeightMarker?.removeOnLayoutChangeListener(contentHeightMarkerLayoutListener)
@@ -393,8 +403,21 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
     contentHeightMarker?.addOnLayoutChangeListener(contentHeightMarkerLayoutListener)
   }
 
+  private fun findSurfaceView(): View? {
+    for (i in 0 until sheetContainer.childCount) {
+      val child = sheetContainer.getChildAt(i)
+      if (child is BottomSheetSurfaceView) return child
+    }
+    return null
+  }
+
   private fun findContentHeightMarker(): View? {
-    val contentView = sheetContainer.getChildAt(0) as? ViewGroup ?: return null
+    // The surface is a sibling of the content wrapper; skip it so the marker is
+    // always read from the content, never from the surface.
+    val contentView =
+      (0 until sheetContainer.childCount)
+        .map { sheetContainer.getChildAt(it) }
+        .firstOrNull { it !== surfaceView } as? ViewGroup ?: return null
     if (contentView.childCount == 0) return null
     return contentView.getChildAt(contentView.childCount - 1)
   }
@@ -402,7 +425,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
   // MARK: - Snap logic
 
   private fun translationY(index: Int): Float {
-    val maxHeight = detentSpecs.maxOfOrNull { it.height } ?: resolvedMaxDetentHeight()
+    val maxHeight = resolvedMaxDetentHeight()
     val snapHeight = detentSpecs.getOrNull(index)?.height ?: 0f
     return maxHeight - snapHeight
   }
@@ -447,7 +470,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
   }
 
   private fun emitPosition() {
-    val maxHeight = detentSpecs.maxOfOrNull { it.height } ?: resolvedMaxDetentHeight()
+    val maxHeight = resolvedMaxDetentHeight()
     val ty = sheetContainer.translationY
     val position = maxHeight - ty
     updateScrim(position)
@@ -464,7 +487,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
   private var lastShadowOffsetY = Float.NaN
 
   private fun updateShadowState(translationY: Float) {
-    val maxDetentHeight = detentSpecs.maxOfOrNull { it.height } ?: resolvedMaxDetentHeight()
+    val maxDetentHeight = resolvedMaxDetentHeight()
     val containerTop = height.toFloat() - maxDetentHeight
     val offsetY = ((containerTop + translationY) / density).toDouble()
     if (offsetY.toFloat() == lastShadowOffsetY) return
@@ -703,7 +726,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
             v
           } ?: 0f
         velocityTracker = null
-        val maxHeight = detentSpecs.maxOfOrNull { it.height } ?: resolvedMaxDetentHeight()
+        val maxHeight = resolvedMaxDetentHeight()
         val currentHeight = maxHeight - sheetContainer.translationY
         val index = bestSnapIndex(currentHeight, velocity, panStartingIndex)
         panStartingIndex = null
@@ -814,6 +837,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
     velocityTracker = null
     contentHeightMarker?.removeOnLayoutChangeListener(contentHeightMarkerLayoutListener)
     contentHeightMarker = null
+    surfaceView = null
     rawDetentSpecs = emptyList()
     detentSpecs = emptyList()
     targetIndex = 0
@@ -881,7 +905,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
   }
 
   private fun currentSheetHeight(): Float {
-    val maxHeight = detentSpecs.maxOfOrNull { it.height } ?: resolvedMaxDetentHeight()
+    val maxHeight = resolvedMaxDetentHeight()
     return maxHeight - sheetContainer.translationY
   }
 

package/common/cpp/react/renderer/components/ReactNativeBottomSheetSpec/ComponentDescriptors.h

@@ -19,4 +19,8 @@ class BottomSheetViewComponentDescriptor final
   }
 };
 
+// The surface needs no custom initial state, so this mirrors the codegen alias.
+using BottomSheetSurfaceViewComponentDescriptor =
+    ConcreteComponentDescriptor<BottomSheetSurfaceViewShadowNode>;
+
 } // namespace facebook::react

package/common/cpp/react/renderer/components/ReactNativeBottomSheetSpec/ShadowNodes.h

@@ -5,6 +5,7 @@
 #include <react/renderer/components/ReactNativeBottomSheetSpec/EventEmitters.h>
 #include <react/renderer/components/ReactNativeBottomSheetSpec/Props.h>
 #include <react/renderer/components/view/ConcreteViewShadowNode.h>
+#include <react/renderer/core/StateData.h>
 
 namespace facebook::react {
 
@@ -22,4 +23,15 @@ class JSI_EXPORT BottomSheetViewShadowNode final
   Point getContentOriginOffset(bool includeTransform) const override;
 };
 
+JSI_EXPORT extern const char BottomSheetSurfaceViewComponentName[];
+
+// The surface needs no custom shadow-node behavior, so this mirrors the codegen
+// alias exactly (state is the default StateData). It only lives here because the
+// custom header search path shadows the generated ShadowNodes.h.
+using BottomSheetSurfaceViewShadowNode = ConcreteViewShadowNode<
+    BottomSheetSurfaceViewComponentName,
+    BottomSheetSurfaceViewProps,
+    BottomSheetSurfaceViewEventEmitter,
+    StateData>;
+
 } // namespace facebook::react

package/ios/BottomSheetComponentView.mm

@@ -1,5 +1,6 @@
 #import "BottomSheetComponentView.h"
 #import "BottomSheetContentView.h"
+#import "BottomSheetSurfaceComponentView.h"
 #import "../common/cpp/react/renderer/components/ReactNativeBottomSheetSpec/BottomSheetStateHelper.h"
 #import "../common/cpp/react/renderer/components/ReactNativeBottomSheetSpec/ComponentDescriptors.h"
 
@@ -95,12 +96,22 @@ using namespace facebook::react;
 
 - (void)mountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView index:(NSInteger)index
 {
-  [_sheetView mountChildComponentView:childComponentView atIndex:index];
+  // Identify the visual surface by component type so the host can own its
+  // geometry. Everything else is treated as content.
+  if ([childComponentView isKindOfClass:BottomSheetSurfaceComponentView.class]) {
+    [_sheetView mountSurfaceComponentView:childComponentView atIndex:index];
+  } else {
+    [_sheetView mountChildComponentView:childComponentView atIndex:index];
+  }
 }
 
 - (void)unmountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView index:(NSInteger)index
 {
-  [_sheetView unmountChildComponentView:childComponentView];
+  if ([childComponentView isKindOfClass:BottomSheetSurfaceComponentView.class]) {
+    [_sheetView unmountSurfaceComponentView:childComponentView];
+  } else {
+    [_sheetView unmountChildComponentView:childComponentView];
+  }
 }
 
 #pragma mark - BottomSheetContentViewDelegate

package/ios/BottomSheetContentView.h

@@ -26,6 +26,8 @@ NS_ASSUME_NONNULL_BEGIN
 - (CGFloat)currentContentOffsetY;
 - (void)mountChildComponentView:(UIView *)childView atIndex:(NSInteger)index;
 - (void)unmountChildComponentView:(UIView *)childView;
+- (void)mountSurfaceComponentView:(UIView *)surfaceView atIndex:(NSInteger)index;
+- (void)unmountSurfaceComponentView:(UIView *)surfaceView;
 - (void)resetSheetState;
 
 @end

package/ios/BottomSheetContentView.mm

@@ -95,6 +95,16 @@
   [_impl unmountChildComponentView:childView];
 }
 
+- (void)mountSurfaceComponentView:(UIView *)surfaceView atIndex:(NSInteger)index
+{
+  [_impl mountSurfaceComponentView:surfaceView atIndex:index];
+}
+
+- (void)unmountSurfaceComponentView:(UIView *)surfaceView
+{
+  [_impl unmountSurfaceComponentView:surfaceView];
+}
+
 - (void)resetSheetState
 {
   [_impl resetSheetState];

package/ios/BottomSheetHostingView.swift

@@ -65,6 +65,7 @@ public final class BottomSheetHostingView: UIView {
   private var panStartingIndex: Int?
   private var isContentInteractionDisabled = false
   private var contentHeightMarker: UIView?
+  private weak var surfaceView: UIView?
   private static var markerObservationContext = 0
 
   override public init(frame: CGRect) {
@@ -127,10 +128,16 @@ public final class BottomSheetHostingView: UIView {
 
     scrimView.frame = bounds
     refreshDetentsFromLayout()
-    let maxHeight = maximumResolvedDetentHeight ?? resolvedMaxDetentHeight
+    let maxHeight = sheetContainerHeight
     sheetContainer.bounds = CGRect(x: 0, y: 0, width: bounds.width, height: maxHeight)
     sheetContainer.center = CGPoint(x: bounds.width / 2, y: bounds.height - maxHeight / 2)
 
+    // The surface fills the full container so it always covers the visible sheet
+    // (the container is translated to the current sheet position), regardless of
+    // how short the content becomes. Sized from the top via frame — never via
+    // anchorPoint.
+    surfaceView?.frame = sheetContainer.bounds
+
     if !hasLaidOut && !detentSpecs.isEmpty {
       let indexToApply = pendingIndex ?? targetIndex
       let clampedIndex = max(0, min(detentSpecs.count - 1, indexToApply))
@@ -138,7 +145,7 @@ public final class BottomSheetHostingView: UIView {
       if animateIn, isInvalidContentDetentTarget(clampedIndex) {
         targetIndex = clampedIndex
         pendingIndex = clampedIndex
-        let closedTy = maximumResolvedDetentHeight ?? bounds.height
+        let closedTy = sheetContainerHeight
         sheetContainer.transform = CGAffineTransform(translationX: 0, y: closedTy)
         emitPosition()
         return
@@ -149,7 +156,7 @@ public final class BottomSheetHostingView: UIView {
       targetIndex = clampedIndex
 
       if animateIn {
-        let closedTy = maximumResolvedDetentHeight ?? bounds.height
+        let closedTy = sheetContainerHeight
         sheetContainer.transform = CGAffineTransform(translationX: 0, y: closedTy)
         emitPosition()
         snapToIndex(targetIndex, velocity: 0, emitIndexChange: false, emitSettle: true)
@@ -231,6 +238,22 @@ public final class BottomSheetHostingView: UIView {
     setNeedsLayout()
   }
 
+  public func mountSurfaceComponentView(_ childView: UIView, atIndex index: Int) {
+    surfaceView = childView
+    sheetContainer.insertSubview(childView, at: index)
+    refreshContentHeightMarker()
+    setNeedsLayout()
+  }
+
+  public func unmountSurfaceComponentView(_ childView: UIView) {
+    if surfaceView === childView {
+      surfaceView = nil
+    }
+    childView.removeFromSuperview()
+    refreshContentHeightMarker()
+    setNeedsLayout()
+  }
+
   public func resetSheetState() {
     activeAnimator?.stopAnimation(true)
     activeAnimator = nil
@@ -244,6 +267,7 @@ public final class BottomSheetHostingView: UIView {
     panStartingIndex = nil
     setContentInteractionEnabled(true)
     stopObservingContentHeightMarker()
+    surfaceView = nil
     sheetContainer.transform = .identity
     scrimView.alpha = 0
     scrimView.isHidden = true
@@ -260,7 +284,7 @@ public final class BottomSheetHostingView: UIView {
   }
 
   private func translationY(for index: Int) -> CGFloat {
-    let maxHeight = maximumResolvedDetentHeight ?? resolvedMaxDetentHeight
+    let maxHeight = sheetContainerHeight
     let snapHeight = detent(at: index).height
     return maxHeight - snapHeight
   }
@@ -297,13 +321,13 @@ public final class BottomSheetHostingView: UIView {
   }
 
   private var currentSheetHeight: CGFloat {
-    let maxHeight = maximumResolvedDetentHeight ?? resolvedMaxDetentHeight
+    let maxHeight = sheetContainerHeight
     let ty = currentTranslationY
     return maxHeight - ty
   }
 
   public var currentContentOffsetY: CGFloat {
-    let maxHeight = maximumResolvedDetentHeight ?? resolvedMaxDetentHeight
+    let maxHeight = sheetContainerHeight
     let containerTop = bounds.height - maxHeight
     let ty = currentTranslationY
     return containerTop + ty
@@ -314,7 +338,7 @@ public final class BottomSheetHostingView: UIView {
   }
 
   private func emitPosition() {
-    let maxHeight = maximumResolvedDetentHeight ?? resolvedMaxDetentHeight
+    let maxHeight = sheetContainerHeight
     let ty = currentTranslationY
     let position = maxHeight - ty
     updateScrim(forPosition: position)
@@ -414,7 +438,7 @@ public final class BottomSheetHostingView: UIView {
   }
 
   @objc private func handlePan(_ gesture: UIPanGestureRecognizer) {
-    let maxHeight = maximumResolvedDetentHeight ?? resolvedMaxDetentHeight
+    let maxHeight = sheetContainerHeight
 
     switch gesture.state {
     case .began:
@@ -576,8 +600,14 @@ public final class BottomSheetHostingView: UIView {
     return min(max(0, maxDetentHeight), bounds.height)
   }
 
-  private var maximumResolvedDetentHeight: CGFloat? {
-    detentSpecs.map(\.height).max()
+  /// Stable coordinate base for the sheet container. The container is sized to
+  /// the full available height rather than the tallest detent, so it stays a
+  /// fixed-size canvas: when content — and thus the `content` detent — shrinks,
+  /// the container does not collapse underneath the sheet, leaving room to
+  /// animate the sheet down to its new height. The surface fills this canvas, so
+  /// the area below the shrunken content stays covered throughout.
+  private var sheetContainerHeight: CGFloat {
+    resolvedMaxDetentHeight
   }
 
   private func resolveDetentSpecs() -> [DetentSpec]? {
@@ -627,7 +657,7 @@ public final class BottomSheetHostingView: UIView {
       return
     }
 
-    let previousMaxHeight = maximumResolvedDetentHeight ?? resolvedMaxDetentHeight
+    let previousMaxHeight = sheetContainerHeight
     // Whether the scrim is currently fully opaque, i.e. the sheet is settled at
     // or above the first non-zero detent. If so, a detent resize must not dip
     // the scrim while the sheet re-anchors to the new geometry.
@@ -642,7 +672,7 @@ public final class BottomSheetHostingView: UIView {
 
     if hasLaidOut, !isPanning {
       targetIndex = max(0, min(detentSpecs.count - 1, targetIndex))
-      let newMaxHeight = maximumResolvedDetentHeight ?? resolvedMaxDetentHeight
+      let newMaxHeight = sheetContainerHeight
       let targetTy = translationY(for: targetIndex)
 
       if let animator = activeAnimator {
@@ -669,21 +699,14 @@ public final class BottomSheetHostingView: UIView {
       } else {
         let currentVisibleHeight = previousMaxHeight - currentTranslationY
         let targetHeight = detent(at: targetIndex).height
-        let isContentDetent = rawDetentSpecs.indices.contains(targetIndex)
-          && rawDetentSpecs[targetIndex].kind == .content
-        let didShrink = targetHeight < currentVisibleHeight - 0.5
-        if isContentDetent, didShrink {
-          // Content shrank: snap immediately. Animating here would expose blank
-          // space below the shrunken content.
-          sheetContainer.transform = CGAffineTransform(translationX: 0, y: targetTy)
-          emitPosition()
-        } else if abs(targetHeight - currentVisibleHeight) <= 0.5 {
+        if abs(targetHeight - currentVisibleHeight) <= 0.5 {
           // No meaningful change.
           sheetContainer.transform = CGAffineTransform(translationX: 0, y: targetTy)
           emitPosition()
         } else {
-          // Detent value changed (or content grew): re-anchor at the current
-          // visible height, then animate to the new target.
+          // The content detent changed (grew or shrank): re-anchor at the
+          // current visible height, then animate to the new target. The surface
+          // covers the full sheet, so a shrink no longer exposes blank space.
           let startTy = min(max(newMaxHeight - currentVisibleHeight, 0), newMaxHeight)
           sheetContainer.transform = CGAffineTransform(translationX: 0, y: startTy)
           scrimPinnedFull = scrimPinnedFull || wasScrimFull
@@ -748,7 +771,10 @@ public final class BottomSheetHostingView: UIView {
   }
 
   private func findContentHeightMarker() -> UIView? {
-    guard let contentView = sheetContainer.subviews.first else { return nil }
+    // The surface is a sibling of the content wrapper; skip it so the marker is
+    // always read from the content, never from the surface.
+    guard let contentView = sheetContainer.subviews.first(where: { $0 !== surfaceView })
+    else { return nil }
     return contentView.subviews.last
   }
 

package/ios/BottomSheetSurfaceComponentView.h

@@ -0,0 +1,13 @@
+#import <React/RCTViewComponentView.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+// Visual surface that sits behind the sheet content. It carries no behavior of
+// its own; the bottom sheet host identifies it by this type and owns its
+// geometry. Its React children provide the appearance only.
+@interface BottomSheetSurfaceComponentView : RCTViewComponentView
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/BottomSheetSurfaceComponentView.mm

@@ -0,0 +1,21 @@
+#import "BottomSheetSurfaceComponentView.h"
+
+#import "../common/cpp/react/renderer/components/ReactNativeBottomSheetSpec/ComponentDescriptors.h"
+
+#import <React/RCTFabricComponentsPlugins.h>
+
+using namespace facebook::react;
+
+@implementation BottomSheetSurfaceComponentView
+
++ (ComponentDescriptorProvider)componentDescriptorProvider
+{
+  return concreteComponentDescriptorProvider<BottomSheetSurfaceViewComponentDescriptor>();
+}
+
+@end
+
+Class<RCTComponentViewProtocol> BottomSheetSurfaceViewCls(void)
+{
+  return BottomSheetSurfaceComponentView.class;
+}

package/lib/module/BottomSheet.js

@@ -3,6 +3,7 @@
 import { StyleSheet, View, useWindowDimensions } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import BottomSheetNativeComponent from './BottomSheetNativeComponent';
+import BottomSheetSurfaceNativeComponent from './BottomSheetSurfaceNativeComponent';
 import { Portal } from "./BottomSheetProvider.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 export { programmatic } from "./bottomSheetUtils.js";
@@ -14,6 +15,7 @@ export { programmatic } from "./bottomSheetUtils.js";
 /** Native bottom sheet that renders inline within the current screen layout. */
 export const BottomSheet = ({
   children,
+  surface,
   style,
   detents = [0, 'content'],
   index,
@@ -65,7 +67,7 @@ export const BottomSheet = ({
     children: /*#__PURE__*/_jsx(View, {
       pointerEvents: "box-none",
       style: StyleSheet.absoluteFill,
-      children: /*#__PURE__*/_jsx(BottomSheetNativeComponent, {
+      children: /*#__PURE__*/_jsxs(BottomSheetNativeComponent, {
         pointerEvents: "box-none",
         style: [{
           position: 'absolute',
@@ -87,7 +89,12 @@ export const BottomSheet = ({
         onIndexChange: handleIndexChange,
         onSettle: handleSettle,
         onPositionChange: handlePositionChange,
-        children: /*#__PURE__*/_jsxs(View, {
+        children: [surface != null && /*#__PURE__*/_jsx(BottomSheetSurfaceNativeComponent, {
+          collapsable: false,
+          pointerEvents: "box-none",
+          style: StyleSheet.absoluteFill,
+          children: surface
+        }), /*#__PURE__*/_jsxs(View, {
           collapsable: false,
           style: {
             flex: 1,
@@ -97,7 +104,7 @@ export const BottomSheet = ({
             collapsable: false,
             pointerEvents: "none"
           })]
-        })
+        })]
       })
     })
   });

package/lib/module/BottomSheet.js.map

@@ -1 +1 @@
-{"version":3,"names":["StyleSheet","View","useWindowDimensions","useSafeAreaInsets","BottomSheetNativeComponent","Portal","jsx","_jsx","jsxs","_jsxs","programmatic","BottomSheet","children","style","detents","index","animateIn","onIndexChange","onSettle","onPositionChange","modal","disableScrollableNegotiation","scrimColor","height","windowHeight","insets","maxHeight","top","nativeDetents","map","detent","isDetentProgrammatic","value","resolveDetentValue","kind","Math","max","min","clampedIndex","length","selectedDetentValue","isCollapsed","handleIndexChange","event","nativeEvent","handleSettle","handlePositionChange","position","sheet","absoluteFill","pointerEvents","left","right","bottom","maxDetentHeight","collapsable","flex"],"sourceRoot":"../../src","sources":["BottomSheet.tsx"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["StyleSheet","View","useWindowDimensions","useSafeAreaInsets","BottomSheetNativeComponent","BottomSheetSurfaceNativeComponent","Portal","jsx","_jsx","jsxs","_jsxs","programmatic","BottomSheet","children","surface","style","detents","index","animateIn","onIndexChange","onSettle","onPositionChange","modal","disableScrollableNegotiation","scrimColor","height","windowHeight","insets","maxHeight","top","nativeDetents","map","detent","isDetentProgrammatic","value","resolveDetentValue","kind","Math","max","min","clampedIndex","length","selectedDetentValue","isCollapsed","handleIndexChange","event","nativeEvent","handleSettle","handlePositionChange","position","sheet","absoluteFill","pointerEvents","left","right","bottom","maxDetentHeight","collapsable","flex"],"sourceRoot":"../../src","sources":["BottomSheet.tsx"],"mappings":";;AAEA,SAASA,UAAU,EAAEC,IAAI,EAAEC,mBAAmB,QAAQ,cAAc;AACpE,SAASC,iBAAiB,QAAQ,gCAAgC;AAElE,OAAOC,0BAA0B,MAAM,8BAA8B;AACrE,OAAOC,iCAAiC,MAAM,qCAAqC;AACnF,SAASC,MAAM,QAAQ,0BAAuB;AAAC,SAAAC,GAAA,IAAAC,IAAA,EAAAC,IAAA,IAAAC,KAAA;AAG/C,SAASC,YAAY,QAAQ,uBAAoB;;AAEjD;AACA;AACA;;AA0CA;AACA,OAAO,MAAMC,WAAW,GAAGA,CAAC;EAC1BC,QAAQ;EACRC,OAAO;EACPC,KAAK;EACLC,OAAO,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC;EACxBC,KAAK;EACLC,SAAS,GAAG,IAAI;EAChBC,aAAa;EACbC,QAAQ;EACRC,gBAAgB;EAChBC,KAAK,GAAG,KAAK;EACbC,4BAA4B,GAAG,KAAK;EACpCC;AACgB,CAAC,KAAK;EACtB,MAAM;IAAEC,MAAM,EAAEC;EAAa,CAAC,GAAGxB,mBAAmB,CAAC,CAAC;EACtD,MAAMyB,MAAM,GAAGxB,iBAAiB,CAAC,CAAC;EAClC,MAAMyB,SAAS,GAAGF,YAAY,GAAGC,MAAM,CAACE,GAAG;EAC3C,MAAMC,aAAa,GAAGd,OAAO,CAACe,GAAG,CAAEC,MAAM,IAAK;IAC5C,MAAMrB,YAAY,GAAGsB,oBAAoB,CAACD,MAAM,CAAC;IACjD,MAAME,KAAK,GAAGC,kBAAkB,CAACH,MAAM,CAAC;IAExC,IAAIE,KAAK,KAAK,SAAS,EAAE;MACvB,OAAO;QACLA,KAAK,EAAE,CAAC;QACRE,IAAI,EAAE,SAAS;QACfzB;MACF,CAAC;IACH;IAEA,OAAO;MACLuB,KAAK,EAAEG,IAAI,CAACC,GAAG,CAAC,CAAC,EAAED,IAAI,CAACE,GAAG,CAACL,KAAK,EAAEN,SAAS,CAAC,CAAC;MAC9CQ,IAAI,EAAE,QAAQ;MACdzB;IACF,CAAC;EACH,CAAC,CAAC;EAEF,MAAM6B,YAAY,GAAGH,IAAI,CAACC,GAAG,CAAC,CAAC,EAAED,IAAI,CAACE,GAAG,CAACtB,KAAK,EAAEa,aAAa,CAACW,MAAM,GAAG,CAAC,CAAC,CAAC;EAC3E,MAAMC,mBAAmB,GAAG1B,OAAO,CAACwB,YAAY,CAAC,GAC7CL,kBAAkB,CAACnB,OAAO,CAACwB,YAAY,CAAC,CAAC,GACzC,CAAC;EACL,MAAMG,WAAW,GAAGD,mBAAmB,KAAK,CAAC;EAC7C,MAAME,iBAAiB,GAAIC,KAAyC,IAAK;IACvE1B,aAAa,GAAG0B,KAAK,CAACC,WAAW,CAAC7B,KAAK,CAAC;EAC1C,CAAC;EACD,MAAM8B,YAAY,GAAIF,KAAyC,IAAK;IAClEzB,QAAQ,GAAGyB,KAAK,CAACC,WAAW,CAAC7B,KAAK,CAAC;EACrC,CAAC;EAED,MAAM+B,oBAAoB,GAAIH,KAE7B,IAAK;IACJ,MAAMpB,MAAM,GAAGoB,KAAK,CAACC,WAAW,CAACG,QAAQ;IACzC5B,gBAAgB,GAAGI,MAAM,CAAC;EAC5B,CAAC;EAED,MAAMyB,KAAK,gBACT1C,IAAA,CAACP,IAAI;IACHc,KAAK,EAAEf,UAAU,CAACmD,YAAa;IAC/BC,aAAa,EAAE9B,KAAK,GAAIqB,WAAW,GAAG,MAAM,GAAG,MAAM,GAAI,UAAW;IAAA9B,QAAA,eAEpEL,IAAA,CAACP,IAAI;MAACmD,aAAa,EAAC,UAAU;MAACrC,KAAK,EAAEf,UAAU,CAACmD,YAAa;MAAAtC,QAAA,eAC5DH,KAAA,CAACN,0BAA0B;QACzBgD,aAAa,EAAC,UAAU;QACxBrC,KAAK,EAAE,CACL;UACEkC,QAAQ,EAAE,UAAU;UACpBI,IAAI,EAAE,CAAC;UACPC,KAAK,EAAE,CAAC;UACRC,MAAM,EAAE,CAAC;UACT;UACA;UACA;UACA9B,MAAM,EAAEC;QACV,CAAC,EACDX,KAAK,CACL;QACFC,OAAO,EAAEc,aAAc;QACvB0B,eAAe,EAAE5B,SAAU;QAC3BX,KAAK,EAAEA,KAAM;QACbC,SAAS,EAAEA,SAAU;QACrBI,KAAK,EAAEA,KAAM;QACbC,4BAA4B,EAAEA,4BAA6B;QAC3DC,UAAU,EAAEA,UAAW;QACvBL,aAAa,EAAEyB,iBAAkB;QACjCxB,QAAQ,EAAE2B,YAAa;QACvB1B,gBAAgB,EAAE2B,oBAAqB;QAAAnC,QAAA,GAEtCC,OAAO,IAAI,IAAI,iBACdN,IAAA,CAACH,iCAAiC;UAChCoD,WAAW,EAAE,KAAM;UACnBL,aAAa,EAAC,UAAU;UACxBrC,KAAK,EAAEf,UAAU,CAACmD,YAAa;UAAAtC,QAAA,EAE9BC;QAAO,CACyB,CACpC,eACDJ,KAAA,CAACT,IAAI;UAACwD,WAAW,EAAE,KAAM;UAAC1C,KAAK,EAAE;YAAE2C,IAAI,EAAE,CAAC;YAAE9B;UAAU,CAAE;UAAAf,QAAA,GACrDA,QAAQ,eACTL,IAAA,CAACP,IAAI;YAACwD,WAAW,EAAE,KAAM;YAACL,aAAa,EAAC;UAAM,CAAE,CAAC;QAAA,CAC7C,CAAC;MAAA,CACmB;IAAC,CACzB;EAAC,CACH,CACP;EAED,IAAI9B,KAAK,EAAE;IACT,oBAAOd,IAAA,CAACF,MAAM;MAAAO,QAAA,EAAEqC;IAAK,CAAS,CAAC;EACjC;EAEA,OAAOA,KAAK;AACd,CAAC;AAED,SAASjB,oBAAoBA,CAACD,MAAc,EAAW;EACrD,IAAI,OAAOA,MAAM,KAAK,QAAQ,IAAIA,MAAM,KAAK,IAAI,EAAE;IACjD,OAAOA,MAAM,CAACrB,YAAY,KAAK,IAAI;EACrC;EACA,OAAO,KAAK;AACd;AAEA,SAASwB,kBAAkBA,CAACH,MAAc,EAAE;EAC1C,IAAI,OAAOA,MAAM,KAAK,QAAQ,IAAIA,MAAM,KAAK,IAAI,EAAE;IACjD,OAAOA,MAAM,CAACE,KAAK;EACrB;EACA,OAAOF,MAAM;AACf","ignoreList":[]}

package/lib/module/BottomSheetSurfaceNativeComponent.ts

@@ -0,0 +1,9 @@
+import { codegenNativeComponent, type ViewProps } from 'react-native';
+
+// The visual surface that sits behind the sheet content. It carries no props of
+// its own: the library identifies it by component type and owns its geometry,
+// sizing it to cover the full sheet so a content shrink never exposes blank
+// space. Its React children provide the visual appearance only.
+export interface NativeProps extends ViewProps {}
+
+export default codegenNativeComponent<NativeProps>('BottomSheetSurfaceView');

package/lib/module/ModalBottomSheet.js.map

@@ -1 +1 @@
-{"version":3,"names":["BottomSheet","jsx","_jsx","ModalBottomSheet","props","modal"],"sourceRoot":"../../src","sources":["ModalBottomSheet.tsx"],"mappings":";;AAAA,SAASA,WAAW,QAA+B,kBAAe;;AAElE;AAAA,SAAAC,GAAA,IAAAC,IAAA;AAIA;AACA,OAAO,MAAMC,gBAAgB,GAAIC,KAA4B,iBAC3DF,IAAA,CAACF,WAAW;EAAA,GAAKI,KAAK;EAAEC,KAAK;AAAA,CAAE,CAChC","ignoreList":[]}
+{"version":3,"names":["BottomSheet","jsx","_jsx","ModalBottomSheet","props","modal"],"sourceRoot":"../../src","sources":["ModalBottomSheet.tsx"],"mappings":";;AAAA,SAASA,WAAW,QAA+B,kBAAe;;AAElE;AAAA,SAAAC,GAAA,IAAAC,IAAA;AAMA;AACA,OAAO,MAAMC,gBAAgB,GAAIC,KAA4B,iBAC3DF,IAAA,CAACF,WAAW;EAAA,GAAKI,KAAK;EAAEC,KAAK;AAAA,CAAE,CAChC","ignoreList":[]}

package/lib/typescript/src/BottomSheet.d.ts

@@ -7,8 +7,20 @@ export { programmatic } from './bottomSheetUtils';
  * Props for the inline bottom-sheet component.
  */
 export interface BottomSheetProps {
-    /** Sheet contents, including any background or scrollable content. */
+    /** Sheet contents, including any scrollable content. */
     children: ReactNode;
+    /**
+     * Optional visual surface (background) rendered behind the content. The
+     * library sizes and positions the surface natively to cover the full sheet,
+     * independently of the content, so a shrinking content height never exposes
+     * blank space. Put a background View here instead of inside `children` when
+     * you want that shrink-safe behavior. When omitted, behavior is unchanged.
+     *
+     * Give the surface element a filling style such as `StyleSheet.absoluteFill`:
+     * it is mounted in a full-size host, so a surface sized only by its own
+     * content would collapse and not show.
+     */
+    surface?: ReactNode;
     /** Additional style applied to the native sheet host view. */
     style?: StyleProp<ViewStyle>;
     /** Snap points for the sheet. Defaults to `[0, 'content']`. */
@@ -35,5 +47,5 @@ export interface BottomSheetProps {
     scrimColor?: string;
 }
 /** Native bottom sheet that renders inline within the current screen layout. */
-export declare const BottomSheet: ({ children, style, detents, index, animateIn, onIndexChange, onSettle, onPositionChange, modal, disableScrollableNegotiation, scrimColor, }: BottomSheetProps) => import("react/jsx-runtime").JSX.Element;
+export declare const BottomSheet: ({ children, surface, style, detents, index, animateIn, onIndexChange, onSettle, onPositionChange, modal, disableScrollableNegotiation, scrimColor, }: BottomSheetProps) => import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=BottomSheet.d.ts.map

package/lib/typescript/src/BottomSheet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BottomSheet.d.ts","sourceRoot":"","sources":["../../../src/BottomSheet.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAMzD,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,EAAE,SAAS,CAAC;IACpB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gEAAgE;IAChE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gFAAgF;AAChF,eAAO,MAAM,WAAW,GAAI,6IAYzB,gBAAgB,4CAwFlB,CAAC"}
+{"version":3,"file":"BottomSheet.d.ts","sourceRoot":"","sources":["../../../src/BottomSheet.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAOzD,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gEAAgE;IAChE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gFAAgF;AAChF,eAAO,MAAM,WAAW,GAAI,sJAazB,gBAAgB,4CAiGlB,CAAC"}

package/lib/typescript/src/BottomSheetSurfaceNativeComponent.d.ts

@@ -0,0 +1,6 @@
+import { type ViewProps } from 'react-native';
+export interface NativeProps extends ViewProps {
+}
+declare const _default: import("react-native/types_generated/Libraries/Utilities/codegenNativeComponent").NativeComponentType<NativeProps>;
+export default _default;
+//# sourceMappingURL=BottomSheetSurfaceNativeComponent.d.ts.map

package/lib/typescript/src/BottomSheetSurfaceNativeComponent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BottomSheetSurfaceNativeComponent.d.ts","sourceRoot":"","sources":["../../../src/BottomSheetSurfaceNativeComponent.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAMtE,MAAM,WAAW,WAAY,SAAQ,SAAS;CAAG;;AAEjD,wBAA6E"}

package/lib/typescript/src/ModalBottomSheet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModalBottomSheet.d.ts","sourceRoot":"","sources":["../../../src/ModalBottomSheet.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEnE,qFAAqF;AACrF,MAAM,WAAW,qBACf,SAAQ,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC;CAAG;AAE5C,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,GAAI,OAAO,qBAAqB,4CAE5D,CAAC"}
+{"version":3,"file":"ModalBottomSheet.d.ts","sourceRoot":"","sources":["../../../src/ModalBottomSheet.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEnE,qFAAqF;AACrF,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CACjD,gBAAgB,EAChB,OAAO,CACR;CAAG;AAEJ,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,GAAI,OAAO,qBAAqB,4CAE5D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/react-native-bottom-sheet",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Provides bottom-sheet components for React Native.",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -33,7 +33,7 @@
     "!**/.*"
   ],
   "scripts": {
-    "example": "yarn workspace @swmansion/react-native-bottom-sheet-example",
+    "example": "bun run --filter @swmansion/react-native-bottom-sheet-example",
     "clean": "del-cli lib",
     "prepare": "lefthook install && bob build",
     "typecheck": "tsc",
@@ -58,23 +58,23 @@
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
-    "@eslint/compat": "1.4.1",
-    "@eslint/eslintrc": "3.3.3",
-    "@eslint/js": "9.39.2",
-    "@react-native/babel-preset": "0.83.0",
-    "@react-native/eslint-config": "0.83.0",
-    "@types/react": "19.2.14",
+    "@eslint/compat": "2.1.0",
+    "@eslint/eslintrc": "3.3.5",
+    "@eslint/js": "9.39.4",
+    "@react-native/babel-preset": "0.85.3",
+    "@react-native/eslint-config": "0.85.3",
+    "@types/react": "19.2.15",
     "babel-plugin-react-compiler": "1.0.0",
     "del-cli": "6.0.0",
-    "eslint": "9.39.2",
+    "eslint": "9.39.4",
     "eslint-config-prettier": "10.1.8",
-    "eslint-plugin-prettier": "5.5.5",
-    "lefthook": "2.1.6",
-    "prettier": "2.8.8",
-    "react": "19.1.0",
-    "react-native": "0.81.5",
-    "react-native-builder-bob": "0.40.18",
-    "react-native-safe-area-context": "5.6.2",
+    "eslint-plugin-prettier": "5.5.6",
+    "lefthook": "2.1.9",
+    "prettier": "3.8.3",
+    "react": "19.2.3",
+    "react-native": "0.85.3",
+    "react-native-builder-bob": "0.41.0",
+    "react-native-safe-area-context": "5.7.0",
     "typescript": "5.9.3"
   },
   "peerDependencies": {
@@ -85,7 +85,7 @@
   "workspaces": [
     "example"
   ],
-  "packageManager": "yarn@4.11.0",
+  "packageManager": "bun@1.3.14",
   "react-native-builder-bob": {
     "source": "src",
     "output": "lib",
@@ -110,7 +110,8 @@
     "jsSrcsDir": "src",
     "ios": {
       "componentProvider": {
-        "BottomSheetView": "BottomSheetComponentView"
+        "BottomSheetView": "BottomSheetComponentView",
+        "BottomSheetSurfaceView": "BottomSheetSurfaceComponentView"
       }
     },
     "android": {
@@ -118,6 +119,7 @@
     }
   },
   "prettier": {
+    "proseWrap": "always",
     "quoteProps": "consistent",
     "singleQuote": true,
     "tabWidth": 2,

package/react-native.config.js

@@ -3,7 +3,10 @@ module.exports = {
     platforms: {
       android: {
         libraryName: 'ReactNativeBottomSheetSpec',
-        componentDescriptors: ['BottomSheetViewComponentDescriptor'],
+        componentDescriptors: [
+          'BottomSheetViewComponentDescriptor',
+          'BottomSheetSurfaceViewComponentDescriptor',
+        ],
         cmakeListsPath: 'src/main/jni/CMakeLists.txt',
       },
     },

package/src/BottomSheet.tsx

@@ -4,6 +4,7 @@ import { StyleSheet, View, useWindowDimensions } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 
 import BottomSheetNativeComponent from './BottomSheetNativeComponent';
+import BottomSheetSurfaceNativeComponent from './BottomSheetSurfaceNativeComponent';
 import { Portal } from './BottomSheetProvider';
 import { type Detent } from './bottomSheetUtils';
 export type { Detent, DetentValue } from './bottomSheetUtils';
@@ -13,8 +14,20 @@ export { programmatic } from './bottomSheetUtils';
  * Props for the inline bottom-sheet component.
  */
 export interface BottomSheetProps {
-  /** Sheet contents, including any background or scrollable content. */
+  /** Sheet contents, including any scrollable content. */
   children: ReactNode;
+  /**
+   * Optional visual surface (background) rendered behind the content. The
+   * library sizes and positions the surface natively to cover the full sheet,
+   * independently of the content, so a shrinking content height never exposes
+   * blank space. Put a background View here instead of inside `children` when
+   * you want that shrink-safe behavior. When omitted, behavior is unchanged.
+   *
+   * Give the surface element a filling style such as `StyleSheet.absoluteFill`:
+   * it is mounted in a full-size host, so a surface sized only by its own
+   * content would collapse and not show.
+   */
+  surface?: ReactNode;
   /** Additional style applied to the native sheet host view. */
   style?: StyleProp<ViewStyle>;
   /** Snap points for the sheet. Defaults to `[0, 'content']`. */
@@ -44,6 +57,7 @@ export interface BottomSheetProps {
 /** Native bottom sheet that renders inline within the current screen layout. */
 export const BottomSheet = ({
   children,
+  surface,
   style,
   detents = [0, 'content'],
   index,
@@ -128,6 +142,15 @@ export const BottomSheet = ({
           onSettle={handleSettle}
           onPositionChange={handlePositionChange}
         >
+          {surface != null && (
+            <BottomSheetSurfaceNativeComponent
+              collapsable={false}
+              pointerEvents="box-none"
+              style={StyleSheet.absoluteFill}
+            >
+              {surface}
+            </BottomSheetSurfaceNativeComponent>
+          )}
           <View collapsable={false} style={{ flex: 1, maxHeight }}>
             {children}
             <View collapsable={false} pointerEvents="none" />

package/src/BottomSheetSurfaceNativeComponent.ts

@@ -0,0 +1,9 @@
+import { codegenNativeComponent, type ViewProps } from 'react-native';
+
+// The visual surface that sits behind the sheet content. It carries no props of
+// its own: the library identifies it by component type and owns its geometry,
+// sizing it to cover the full sheet so a content shrink never exposes blank
+// space. Its React children provide the visual appearance only.
+export interface NativeProps extends ViewProps {}
+
+export default codegenNativeComponent<NativeProps>('BottomSheetSurfaceView');

package/src/ModalBottomSheet.tsx

@@ -1,8 +1,10 @@
 import { BottomSheet, type BottomSheetProps } from './BottomSheet';
 
 /** Props for the modal bottom-sheet variant rendered through the provider portal. */
-export interface ModalBottomSheetProps
-  extends Omit<BottomSheetProps, 'modal'> {}
+export interface ModalBottomSheetProps extends Omit<
+  BottomSheetProps,
+  'modal'
+> {}
 
 /** Bottom sheet presented above the current UI with a scrim. */
 export const ModalBottomSheet = (props: ModalBottomSheetProps) => (