Skip to content

v0.18.0-next.4

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 07 Nov 17:40
7031d2b

Overview

Changes

  • Added floating cards to BottomSheet and ModalBottomSheet. Each detent can set left, right, and bottom insets. The gaps change smoothly as you drag, and taps in the gaps reach the scrim or the view behind the sheet.

  • Added surfaceStyle for corner radii and shadows. The sheet clips both its background and its content to the same shape. borderCurve is iOS-only, and elevation is 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. Use scrimAccessibilityLabel to localize the label.

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

  • Changed lazy to unmount the sheet’s native view along with its content once the closing animation settles. While unmounted, the sheet emits no onPositionChange events.

  • Fixed iOS scroll handoff when a drag reverses direction. With handoff enabled 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

  1. Check the peer dependencies: 0.18.0-next.4 requires React Native 0.82.0 or later and React 19.1.1 or later.

  2. Move modal scrim opacity onto each detent and remove the programmatic import: Replace programmatic(value) with { value, programmatic: true }. Replace the scrimOpacities array with scrimOpacity on the corresponding detents. Bare numbers, percentages, and 'content' still work. An omitted opacity defaults to 0 for a closed detent and 1 for 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, use ModalDetent[].

  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. topInset applies to every detent. Put side and bottom gaps in each detent’s insets object.

  4. Move corner radii and shadows from surface to surfaceStyle: Keep the visual fill on surface, such as a background color, image, or gradient. Move the existing corner radii to surfaceStyle so 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 both BottomSheet and ModalBottomSheet.

    surface={
      <View style={[StyleSheet.absoluteFill, { backgroundColor: 'white' }]} />
    }
    surfaceStyle={{
      borderTopLeftRadius: 24,
      borderTopRightRadius: 24,
      boxShadow: '0 -4 16 rgba(0, 0, 0, 0.2)',
    }}

    If your surface already provides only the fill, no change is needed.

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