Bottom Sheet

A performant interactive bottom sheet with fully configurable options 🚀

Initially, this project was a cloned of react-native-scroll-bottom-sheet by @rgommezz ❤️. However, it is been fully re-written to add extra functionalities and simplify the approach.

---

Table of Contents

1. Features
2. Installation
   • Version v2 with Reanimated v1
   • Version v3 with Reanimated v2
3. Usage
   • Custom Handle
   • React Navigation Integration
   • Touchables
4. Props
5. Methods
6. Hooks
7. Scrollables
   • BottomSheetFlatList
   • BottomSheetSectionList
   • BottomSheetScrollView
   • BottomSheetView
8. To Do
9. FAQ
10. Credits
11. License

Features

• Smooth interactions & snapping animations.
• Support FlatList, SectionList, ScrollView & View scrolling interactions.
• Support React Navigation Integration.
• Compatible with Reanimated v1 & v2.
• Compatible with Expo.
• Written in TypeScript.

Installation

Version v2 with Reanimated v1

Link to version 2 branch

yarn add @gorhom/bottom-sheet
# or
npm install @gorhom/bottom-sheet

⚠️ You need to install react-native-reanimated & react-native-gesture-handler and follow their installation instructions.

Version v3 with Reanimated v2

Link to version 3 branch

this version is written with Reanimated v2, although this version is still in alpha phase, yet it provides all version 1 functionalities with the huge performance boost, thanks to Reanimated v2 ❤️

yarn add @gorhom/bottom-sheet@3.0.0-alpha.0
# or
npm install @gorhom/bottom-sheet@3.0.0-alpha.0

⚠️ You need to install react-native-reanimated v2 & react-native-gesture-handler and follow their installation instructions.

Usage

import React, { useCallback, useMemo, useRef } from 'react';
import { View, StyleSheet } from 'react-native';
import BottomSheet from '@gorhom/bottom-sheet';

const App = () => {
  // hooks
  const bottomSheetRef = useRef<BottomSheet>(null);

  // variables
  const snapPoints = useMemo(() => ['25%', '50%', '90%'], []);

  // callbacks
  const handleSheetChanges = useCallback((index: number) => {
    console.log('handleSheetChanges', index);
  }, []);

  // renders
  return (
    <View style={styles.container}>
      <BottomSheet
        ref={bottomSheetRef}
        initialSnapIndex={1}
        snapPoints={snapPoints}
        onChange={handleSheetChanges}
      >
        {/* INSERT A SCROLLABLE HERE */}
      </BottomSheet>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 24,
  },
});

export default App;

Props

initialSnapIndex

Initial snap index. You also could provide {-1} to initiate bottom sheet in closed state.

required: NO | type: number | default: 0

snapPoints

Points for the bottom sheet to snap to, points should be sorted from bottom to top. It accepts array of number, string or mix. String values should be a percentage.

required: YES | type: Array<string | number>
example: [100, '50%', '90%']

topInset

Top inset value helps to calculate percentage snap points values. usually comes from @react-navigation/stack hook useHeaderHeight or from react-native-safe-area-context hook useSafeArea.

required: NO | type: number | default: 0

animationDuration

Snapping animation duration.

required: NO | type: number | default: 500

animationEasing

Snapping animation easing function.

required: NO | type: Animated.EasingFunction | default: Easing.out(Easing.back(0.75))

animatedPosition

Animated shared value to be used as a callback for the position node internally.

required: NO | type: Animated.SharedValue

animatedPositionIndex

Animated shared value to be used as a callback for the position index node internally.

required: NO | type: Animated.SharedValue

handleComponent

Component to be placed as a sheet handle.

required: NO | type: React.FC<BottomSheetHandleProps>

backgroundComponent

Component to be placed as a background.

required: NO | type: React.FC

onChange

Callback when sheet position changed to a provided point.

required: NO | type: (index: number) => void

children

A scrollable node or normal view.

required: YES | type: () => React.ReactNode | React.ReactNode[] | React.ReactNode

Methods

snapTo

Snap to one of the provided points from snapPoints.

type: (index: number) => void

expand

Snap to the maximum provided point from snapPoints.

type: () => void

collapse

Snap to the minimum provided point from snapPoints.

type: () => void

close

Close the bottom sheet.

type: () => void

Hooks

useBottomSheet

The library provide useBottomSheet hook to provide the bottom sheet methods, anywhere inside the sheet content.

type: BottomSheetMethods

Scrollables

This library provides a pre-integrated views that utilise an internal functionalities with the bottom sheet to allow smooth interactions. These views i called them Scrollables and they are:

• BottomSheetFlatList
• BottomSheetSectionList
• BottomSheetScrollView
• BottomSheetView

To Do

• Add tablets support.
• Add Reanimated v2 support.

FAQ

How this library differ from reanimated-bottom-sheet or react-native-scroll-bottom-sheet?

This library was built to provide the most native-like experience and could fit any use-case that developers wants it to be.

While both libraries providing similar experience, but they still missing the following:

• reanimated-bottom-sheet
  • Seamless gesture interaction between the sheet and the content.
• react-native-scroll-bottom-sheet
  • Extracting scrollable content to allow developers customize the sheet content, like integrate React Navigation as the sheet content.

Both libraries are great! and I have used both of them at my work ❤️

How can I integrate React Navigation?

here you go React Navigation Integration :)

Will this library support Reanimated v2?

Yes 🎉

Built With ❤️

• react-native-reanimated
• react-native-gesture-handler
• react-native-redash
• @react-native-community/bob

Author

• Mo Gorhom

License

MIT

Liked the library? 😇

---