Repository navigation
Releases
v1.1.0
Overview
Changes
- Added
maxWidthandplacementtoBottomSheetandModalBottomSheeton iOS, Android, and web. Both props can change while the sheet is open.- Set
maxWidthto cap the sheet’s width in points, including the detent’s sideinsets. Narrower containers still use their available width. OmitmaxWidthor passInfinityfor no cap. - Set
placementto align the sheet when the cap leaves extra space. The default is'center'. Use'start'or'end'to align it with the corresponding edge in the current layout direction.
- Set
- Reduced stuttering on iOS while a sheet animates to a detent.
- Fixed a final-frame jump on iOS, Android, and web. The sheet now slows to a stop at its target detent, most noticeably when opening from closed to full height.
v1.1.0-next.2
Overview
- addressed: #131
Changes
- Fixed a final-frame jump as the sheet settled on a detent on iOS, Android, and web. The sheet now slows smoothly to a stop at the target, most noticeably when opening from closed to full height.
v1.1.0-next.1
Overview
Changes
- Added
maxWidthandplacementtoBottomSheetandModalBottomSheet, so a sheet doesn’t stretch across a tablet, foldable, desktop browser, or phone in landscape.maxWidthcaps the sheet’s width in points, including its detent’s sideinsets. The card fills a column up tomaxWidthwide, between its insets, as it would on a screen that wide. A screen narrower thanmaxWidthis filled as before. Leave it unset, or passInfinity, for no cap.placementpositions a sheet thatmaxWidthmakes narrower than its host:'center'(the default),'start', or'end'.'start'and'end'follow the layout direction, like a detent’sstartandendinsets.- Both can change while the sheet is open.
- Fixed stuttering on iOS while a sheet animates to a detent.
v1.0.0
Changes
-
Changed
nativeOverlaytowindowOverlayonModalBottomSheet. The behavior is the same. -
Changed
settleDurationfrom seconds to milliseconds. The default is450. In development, a value below10logs a warning, since it is likely a leftover value in seconds. -
Changed close requests on
ModalBottomSheetso one rule covers every way of asking a sheet to close without dragging it: a scrim tap, a screen reader’s dismiss action, Android system back, and Escape on Android and the web.-
With
onCloseRequest, each of these only calls the handler. The sheet does not move, so the handler can confirm first, close a sheet that has no closed detent, or ignore the request. -
Without
onCloseRequest, each of these snaps the sheet to its closed detent and reports it throughonIndexChange. This requires a visible scrim and a closed detent that is notprogrammatic. -
Dragging the sheet closed is unchanged and always reports through
onIndexChange.
-
-
Added
onCloseRequestsupport on iOS. It is called for scrim taps, the scrim’s Dismiss button, and the VoiceOver escape gesture. -
Changed the default for Android system back and for Escape on Android and the web. A modal sheet without
onCloseRequestnow closes instead of letting the input pass to the app, and keeps consuming it until the closing animation finishes. -
Changed Escape routing on the web to match Android. The top modal sheet blocks the sheets it covers even when it does not act on Escape.
-
Added
startandendto a detent’sinsets. They follow the layout direction and take precedence overleftorright, whichever they resolve to. On the web, the layout direction is the document’s. -
Fixed start and end corner radii in
surfaceStyleon the web in right-to-left documents. -
Changed
scrimColorto accept anyColorValue, includingPlatformColorandDynamicColorIOS. -
Changed the type of
wrapNativeViewso it no longer exposes the internal native props. PassingAnimated.createAnimatedComponentworks as before. -
Added the
BottomSheetProviderPropstype export. -
Added
react-domandreact-native-webas optional peer dependencies.
Migrating from 0.18.1
-
Rename
nativeOverlaytowindowOverlay: Keep the value you passed. -
Convert
settleDurationto milliseconds: Multiply your value by1000.// 0.18.1 settleDuration={0.55} // 1.0.0 settleDuration={550}
-
Review sheets that use
onCloseRequest: The handler now also receives scrim taps and screen reader dismiss actions, on every platform including iOS, and the sheet no longer closes by itself for those. If your handler does not already close the sheet, setindexto the closed detent in it.onCloseRequest={() => setIndex(0)}
-
Review modal sheets without
onCloseRequest: Android system Back and Escape now close the sheet. To keep the sheet open, add anonCloseRequesthandler that does nothing, or make the closed detentprogrammatic. -
Update typed
wrapNativeViewwrappers: If you annotated the wrapper’s parameter with the native props type, useComponentType<any>.
v0.18.1
Overview
Changes
- Fixed screen reader navigation for
ModalBottomSheetwhen presented through the default portal. VoiceOver on iOS and TalkBack on Android skip the screen and any sheets behind the topmost sheet. Closing it makes the newly uncovered content accessible again. - Fixed an iOS gesture that left a partially expanded sheet in place. When the list is at its top, dragging the vertical scroll indicator upward can now expand the sheet.
- Fixed vertical scroll indicator sizing on iOS and Android 10 or later. The indicator now fits the visible portion of the list as the sheet expands or collapses.
v0.18.0
Overview
- addressed: #18, #46, #52, #55, #103
- external contributors: @dkulakov, @falcondpr, @NicholasBoccuzzi
Changes
-
Added web support for
BottomSheetandModalBottomSheet. Installreact-domandreact-native-webalongside the library to use sheets on the web. -
Added floating cards. Each detent can set
left,right, andbottomgaps throughinsets. 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
surfaceStylefor corner radii and shadows. The sheet clips its background and content to the same outline while allowing the shadow to extend beyond it.borderCurveis iOS-only, andelevationis Android-only. -
Added
lazyto 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 noonPositionChangeevents.lazydefaults tofalseand only applies when there is a closed detent. -
Added
settleDurationto both sheet components. It accepts a finite duration greater than0, in seconds. Animations that start from rest take the full duration. The default is0.45seconds on all platforms, up from about0.2seconds 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
settleDurationwithout 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. UsescrimAccessibilityLabelto localize the button label. -
Changed modal stacking so the most recently opened or reopened sheet appears on top.
nativeOverlaysheets stay above portal sheets. Android back and Escape on Android and web route to the topmost eligible sheet. -
Fixed Android system back bypassing
onCloseRequeston 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
handoffenabled 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
-
Check the minimum versions:
0.18.0requires React Native0.82.0or later and React19.1.1or later. -
Move detent options into
detents: Remove theprogrammaticimport and replaceprogrammatic(value)with{ value, programmatic: true }. ReplacescrimOpacitieswithscrimOpacityon 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 to0for a closed detent and1for an open one. For explicitly typed arrays containingscrimOpacity, useModalDetent[].// 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 }, ]}
-
Replace
extendUnderStatusBarwithtopInset: UsetopInset={0}where you previously passedextendUnderStatusBar={true}. If you passedfalse, omittopInsetto keep the default status-bar clearance. -
Move corner radii and shadows from
surfacetosurfaceStyle: Keep the background color, image, or gradient onsurface. -
Rename
scrollableNegotiationtoscrollCoordination: Keep your existing mode or{ expand, collapse }value. RenameScrollableNegotiationandScrollableNegotiationModetoScrollCoordinationandScrollCoordinationMode. If you useddisableScrollableNegotiation={true}, replace it withscrollCoordination="none". If you passedfalse, omit the prop.
v0.18.0-next.5
Overview
- external contributors: @NicholasBoccuzzi
Changes
- Added
settleDurationtoBottomSheetandModalBottomSheetto control how long the sheet takes to settle at a detent. It accepts a finite number greater than0, in seconds. The default is0.45seconds on iOS, Android, and web. Android previously settled in about0.2seconds. - Improved detent selection on all platforms. A gentle swipe up or down can now reach the next detent before crossing the midpoint. If you pause before lifting your finger, the sheet snaps to the nearest detent.
- Improved fast flicks on all platforms. The sheet carries its release speed toward the target detent and can arrive before
settleDurationwithout overshooting. Animations that start from rest, such as programmaticindexchanges, take the full duration.
v0.18.0-next.4
Overview
- addressed: #18, #52
- external contributors: @dkulakov, @falcondpr
Changes
-
Added floating cards to
BottomSheetandModalBottomSheet. Each detent can setleft,right, andbottominsets. The gaps change smoothly as you drag, and taps in the gaps reach the scrim or the view behind the sheet. -
Added
surfaceStylefor corner radii and shadows. The sheet clips both its background and its content to the same shape.borderCurveis iOS-only, andelevationis Android-only. -
Added accessible dismissal to
ModalBottomSheet. When tapping the scrim would close the sheet, screen readers can activate its Dismiss button. VoiceOver users can also perform the escape gesture on iOS, and TalkBack users can invoke the Dismiss action from inside the sheet on Android. These actions select the closed detent directly. UsescrimAccessibilityLabelto localize the label. -
Changed modal stacking so the most recently opened or reopened sheet appears on top.
nativeOverlaysheets stay above portal sheets. Android back and supported Escape-key requests go to the topmost eligible sheet. -
Changed
lazyto unmount the sheet’s native view along with its content once the closing animation settles. While unmounted, the sheet emits noonPositionChangeevents. -
Fixed iOS scroll handoff when a drag reverses direction. With
handoffenabled for the new direction, the same touch can expand or collapse 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 recycled modal sheet could reopen with the wrong scrim opacity.
Migrating from 0.18.0-next.3
-
Check the peer dependencies:
0.18.0-next.4requires React Native0.82.0or later and React19.1.1or later. -
Move modal scrim opacity onto each detent and remove the
programmaticimport: Replaceprogrammatic(value)with{ value, programmatic: true }. Replace thescrimOpacitiesarray withscrimOpacityon the corresponding detents. Bare numbers, percentages, and'content'still work. An omitted opacity defaults to0for a closed detent and1for an open one.// Before: detents={[0, programmatic(320), '100%']} scrimOpacities={[0, 0.4]} // After: detents={[ 0, { value: 320, programmatic: true, scrimOpacity: 0.4 }, { value: '100%', scrimOpacity: 0.4 }, ]}
The old array reused its last entry for later detents. Repeat that value wherever you relied on it. For a separately typed modal detent array that uses
scrimOpacity, useModalDetent[]. -
Replace
extendUnderStatusBarwithtopInset: UsetopInset={0}where you previously passedextendUnderStatusBar={true}. If you passedfalse, omittopInsetto keep the default status-bar clearance.topInsetapplies to every detent. Put side and bottom gaps in each detent’sinsetsobject. -
Move corner radii and shadows from
surfacetosurfaceStyle: Keep the visual fill onsurface, such as a background color, image, or gradient. Move the existing corner radii tosurfaceStyleso the sheet clips both the fill and its content to the same outline. Move shadow styles there as well so the shadow can draw outside the card. This applies to bothBottomSheetandModalBottomSheet.surface={ <View style={[StyleSheet.absoluteFill, { backgroundColor: 'white' }]} /> } surfaceStyle={{ borderTopLeftRadius: 24, borderTopRightRadius: 24, boxShadow: '0 -4 16 rgba(0, 0, 0, 0.2)', }}
If your
surfacealready provides only the fill, no change is needed. -
Rename
scrollableNegotiationtoscrollCoordination: Keep your existing mode or{ expand, collapse }value. Rename the exported typesScrollableNegotiationandScrollableNegotiationModetoScrollCoordinationandScrollCoordinationMode. If you used the deprecateddisableScrollableNegotiationflag, replacetruewithscrollCoordination="none"or omit the prop forfalse.
v0.18.0-next.3
Overview
- addressed: #46
Changes
- Added an optional
lazyprop toBottomSheetandModalBottomSheet, defaulting tofalse. When this is enabled,childrenandsurfacemount before opening and unmount after the closing animation finishes. Reopening during closing preserves the mounted content; reopening after a full close resets its state. Has no effect when no detent is closed.
v0.18.0-next.2
Overview
Changes
- Fixed Android system back bypassing
onCloseRequestfor portalModalBottomSheetpresentations on legacy back paths, causing the application to exit or move to the background instead of letting the sheet handle the request. - Fixed iOS and Android drags that start sideways or diagonally inside a vertical scrollable scrolling the content instead of expanding or collapsing the sheet. These gestures now follow
scrollableNegotiation, while horizontal scrollables retain sideways gestures.