@swmansion/react-native-bottom-sheet 0.10.2 → 0.12.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,64 @@ its&nbsp;color:
 <ModalBottomSheet
   index={index}
   onIndexChange={setIndex}
+  surface={/* ... */}
   scrimColor="rgba(0, 0, 0, 0.3)"
 >
   {/* ... */}
 </ModalBottomSheet>
 ```
 
+By default, the scrim fades in as the sheet opens and then holds at full
+opacity, so detents above the first share the same scrim. Use `scrimOpacities`
+to control the opacity at each detent: It takes one value in 0–1 per detent,
+indexed to match `detents`, and interpolates linearly as the sheet is dragged
+between them. A shorter array reuses its last value for any remaining detents.
+
+The default maps each detent to 0 when it is closed and 1 otherwise, so the
+scrim is transparent at any closed detent and fully opaque at every open one,
+whatever order the detents are passed in.
+
+To keep the scrim deepening across every detent, pass one value per detent:
+
+```tsx
+<ModalBottomSheet
+  index={index}
+  onIndexChange={setIndex}
+  detents={[0, 300, 'content']}
+  scrimColor="rgba(0, 0, 0, 0.3)"
+  scrimOpacities={[0, 0.5, 1]}
+  surface={/* ... */}
+>
+  {/* ... */}
+</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 +214,7 @@ set&nbsp;`disableScrollableNegotiation`:
 <BottomSheet
   index={index}
   onIndexChange={setIndex}
+  surface={/* ... */}
   disableScrollableNegotiation
 >
   {/* ... */}
@@ -134,18 +228,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 +264,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 +287,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 +305,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 +325,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

@@ -83,11 +83,15 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
   private var scrimPressed = false
   private var scrimTouchActive = false
   private var scrimColor = Color.TRANSPARENT
+  // The JS layer always supplies a per-detent array; the fully-opaque fallback
+  // only guards against empty input (indexing requires a non-empty array).
+  private var scrimOpacities = listOf(1f)
   private var scrimProgress = 0f
   private var suppressScrimForClosingTarget = false
   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 +170,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 +181,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 +202,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
@@ -247,11 +258,22 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
     invalidate()
   }
 
+  fun setScrimOpacities(values: List<Float>) {
+    scrimOpacities = if (values.isEmpty()) listOf(1f) else values
+    updateScrim()
+  }
+
   fun setMaxDetentHeight(maxDetentHeight: Double) {
     this.maxDetentHeight = (maxDetentHeight * density).toFloat()
     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 +316,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 +330,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 +359,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 +403,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
   }
 
   private fun refreshContentHeightMarker() {
+    surfaceView = findSurfaceView()
     val marker = findContentHeightMarker()
     if (marker === contentHeightMarker) return
     contentHeightMarker?.removeOnLayoutChangeListener(contentHeightMarkerLayoutListener)
@@ -393,8 +411,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 +433,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 +478,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 +495,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 +734,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 +845,7 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
     velocityTracker = null
     contentHeightMarker?.removeOnLayoutChangeListener(contentHeightMarkerLayoutListener)
     contentHeightMarker = null
+    surfaceView = null
     rawDetentSpecs = emptyList()
     detentSpecs = emptyList()
     targetIndex = 0
@@ -854,18 +886,55 @@ class BottomSheetView(context: Context) : ReactViewGroup(context) {
 
     // While the sheet is fully open and only its content/detent geometry is
     // resizing, the position momentarily lags the grown detent height. Keep the
-    // scrim at full opacity instead of dipping it until the re-anchor settles.
+    // scrim pinned to the fully-open opacity instead of dipping it until the
+    // re-anchor settles.
     if (scrimPinnedFull) {
-      scrimProgress = 1f
+      scrimProgress = fullyOpenScrimOpacity()
       invalidate()
       return
     }
 
-    val threshold = firstNonZeroDetentHeight
-    scrimProgress = if (threshold <= 0f) 0f else (position / threshold).coerceIn(0f, 1f)
+    scrimProgress = scrimOpacityAt(position)
     invalidate()
   }
 
+  /** The opacity at the tallest detent, held while the sheet re-anchors. */
+  private fun fullyOpenScrimOpacity(): Float {
+    val maxHeight = detentSpecs.maxOfOrNull { it.height } ?: return 1f
+    return scrimOpacityAt(maxHeight)
+  }
+
+  /**
+   * Interpolates the scrim opacity for a sheet height by bracketing it between adjacent detent
+   * heights and lerping each detent index's configured value.
+   */
+  private fun scrimOpacityAt(position: Float): Float {
+    if (detentSpecs.isEmpty()) return 0f
+    val pairs =
+      detentSpecs.indices
+        .map { index ->
+          detentSpecs[index].height to
+            scrimOpacities[index.coerceAtMost(scrimOpacities.size - 1)].coerceIn(0f, 1f)
+        }
+        .sortedBy { it.first }
+
+    val first = pairs.first()
+    val last = pairs.last()
+    if (position <= first.first) return first.second
+    if (position >= last.first) return last.second
+
+    for (i in 1 until pairs.size) {
+      val upper = pairs[i]
+      if (position <= upper.first) {
+        val lower = pairs[i - 1]
+        val span = upper.first - lower.first
+        val t = if (span <= 0f) 1f else (position - lower.first) / span
+        return lower.second + (upper.second - lower.second) * t
+      }
+    }
+    return last.second
+  }
+
   private fun hideScrim() {
     scrimProgress = 0f
     invalidate()
@@ -881,7 +950,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/android/src/main/java/com/swmansion/reactnativebottomsheet/BottomSheetViewManager.kt

@@ -138,6 +138,17 @@ class BottomSheetViewManager :
     view.setScrimColor(scrimColor)
   }
 
+  @ReactProp(name = "scrimOpacities")
+  override fun setScrimOpacities(view: BottomSheetView, value: ReadableArray?) {
+    val opacities = mutableListOf<Float>()
+    if (value != null) {
+      for (i in 0 until value.size()) {
+        opacities.add(value.getDouble(i).toFloat())
+      }
+    }
+    view.setScrimOpacities(opacities)
+  }
+
   override fun onDropViewInstance(view: BottomSheetView) {
     super.onDropViewInstance(view)
     view.destroy()

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"
 
@@ -85,6 +86,14 @@ using namespace facebook::react;
     [_sheetView setScrimColor:RCTUIColorFromSharedColor(newViewProps.scrimColor)];
   }
 
+  if (newViewProps.scrimOpacities != oldViewProps.scrimOpacities) {
+    NSMutableArray<NSNumber *> *opacities = [NSMutableArray new];
+    for (const auto &opacity : newViewProps.scrimOpacities) {
+      [opacities addObject:@(opacity)];
+    }
+    [_sheetView setScrimOpacities:opacities];
+  }
+
   [super updateProps:props oldProps:oldProps];
 }
 
@@ -95,12 +104,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

@@ -23,9 +23,12 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)setMaxDetentHeight:(CGFloat)maxDetentHeight;
 - (void)setDetentIndex:(NSInteger)newIndex;
 - (void)setScrimColor:(UIColor *_Nullable)color;
+- (void)setScrimOpacities:(NSArray<NSNumber *> *)opacities;
 - (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