v0.18.0

Overview

• addressed: #18, #46, #52, #55, #103
• external contributors: @dkulakov, @falcondpr, @NicholasBoccuzzi

Changes

• Added web support for BottomSheet and ModalBottomSheet. Install react-dom and react-native-web alongside the library to use sheets on the web.

• Added floating cards. Each detent can set left, right, and bottom gaps through insets. The gaps change smoothly as the sheet moves between detents. Taps in the gaps reach the modal scrim or the view behind an inline sheet.

• Added surfaceStyle for corner radii and shadows. The sheet clips its background and content to the same outline while allowing the shadow to extend beyond it. borderCurve is iOS-only, and elevation is Android-only.

• Added lazy to both sheet components. When enabled, the sheet mounts before opening and unmounts after the closing animation finishes. Reopening mid-animation preserves content state. Reopening after a full close starts with fresh state. An unmounted sheet emits no onPositionChange events. lazy defaults to false and only applies when there is a closed detent.

• Added settleDuration to both sheet components. It accepts a finite duration greater than 0, in seconds. Animations that start from rest take the full duration. The default is 0.45 seconds on all platforms, up from about 0.2 seconds on Android.

• Improved snapping on all platforms. A gentle swipe can reach the next detent before crossing the midpoint. Pausing before release selects the nearest detent. A fast flick carries its speed into the animation and can reach the target before settleDuration without overshooting.

• Added accessible dismissal for ModalBottomSheet. When tapping the scrim would close the sheet, screen reader users can activate its Dismiss button, perform the VoiceOver escape gesture on iOS, or invoke the TalkBack Dismiss action on Android. These actions select the closed detent directly. Use scrimAccessibilityLabel to localize the button label.

• Changed modal stacking so the most recently opened or reopened sheet appears on top. nativeOverlay sheets stay above portal sheets. Android back and Escape on Android and web route to the topmost eligible sheet.

• Fixed Android system back bypassing onCloseRequest on portal sheets. This could send the app to the background on Android 10 while the sheet was open.

• Fixed drags that start sideways or diagonally inside a vertical scrollable on iOS and Android. They now respect scrollCoordination. Horizontal scrollables still handle sideways gestures.

• Fixed scroll handoff on iOS when a drag reverses direction. With handoff enabled for the new direction, the same touch can move the sheet after a bounce or pull-to-refresh clears. A touch that interrupts a snap without moving the sheet now lets the snap resume.

• Fixed an iOS issue where a modal sheet could reopen with the wrong scrim opacity.

Migrating from 0.17.1

1. Check the minimum versions: 0.18.0 requires React Native 0.82.0 or later and React 19.1.1 or later.

2. Move detent options into detents: Remove the programmatic import and replace programmatic(value) with { value, programmatic: true }. Replace scrimOpacities with scrimOpacity on each corresponding modal detent. The old array reused its last entry for later detents, so repeat that value wherever you relied on it. An omitted opacity defaults to 0 for a closed detent and 1 for an open one. For explicitly typed arrays containing scrimOpacity, use ModalDetent[].

   // 0.17.1
   detents={[0, programmatic(320), '100%']}
   scrimOpacities={[0, 0.4]}
   
   // 0.18.0
   detents={[
     0,
     { value: 320, programmatic: true, scrimOpacity: 0.4 },
     { value: '100%', scrimOpacity: 0.4 },
   ]}

3. Replace extendUnderStatusBar with topInset: Use topInset={0} where you previously passed extendUnderStatusBar={true}. If you passed false, omit topInset to keep the default status-bar clearance.

4. Move corner radii and shadows from surface to surfaceStyle: Keep the background color, image, or gradient on surface.

5. Rename scrollableNegotiation to scrollCoordination: Keep your existing mode or { expand, collapse } value. Rename ScrollableNegotiation and ScrollableNegotiationMode to ScrollCoordination and ScrollCoordinationMode. If you used disableScrollableNegotiation={true}, replace it with scrollCoordination="none". If you passed false, omit the prop.