@gorhom/bottom-sheet

What is @gorhom/bottom-sheet?

@gorhom/bottom-sheet is a performant and customizable bottom sheet component for React Native. It allows developers to create modal-like bottom sheets that can be used for various purposes such as displaying additional content, forms, or actions. The package is highly flexible and supports gestures, animations, and various customization options.

What are @gorhom/bottom-sheet's main functionalities?

Basic Bottom Sheet

This code demonstrates how to create a basic bottom sheet with three snap points (collapsed, half-expanded, and fully expanded). The bottom sheet can be opened by pressing a button.

```jsx
import React, { useRef } from 'react';
import { View, Text, Button } from 'react-native';
import BottomSheet from '@gorhom/bottom-sheet';

const App = () => {
  const bottomSheetRef = useRef(null);
  return (
    <View style={{ flex: 1 }}>
      <Button title="Open Bottom Sheet" onPress={() => bottomSheetRef.current?.expand()} />
      <BottomSheet ref={bottomSheetRef} snapPoints={[0, '50%', '100%']}>
        <View style={{ flex: 1, alignItems: 'center' }}>
          <Text>Bottom Sheet Content</Text>
        </View>
      </BottomSheet>
    </View>
  );
};

export default App;
```

Custom Handle Component

This code demonstrates how to use a custom handle component for the bottom sheet. The custom handle can be styled and customized as needed.

```jsx
import React, { useRef } from 'react';
import { View, Text, Button } from 'react-native';
import BottomSheet, { BottomSheetHandle } from '@gorhom/bottom-sheet';

const CustomHandle = () => (
  <View style={{ padding: 20, backgroundColor: 'lightgray' }}>
    <Text>Custom Handle</Text>
  </View>
);

const App = () => {
  const bottomSheetRef = useRef(null);
  return (
    <View style={{ flex: 1 }}>
      <Button title="Open Bottom Sheet" onPress={() => bottomSheetRef.current?.expand()} />
      <BottomSheet ref={bottomSheetRef} snapPoints={[0, '50%', '100%']} handleComponent={CustomHandle}>
        <View style={{ flex: 1, alignItems: 'center' }}>
          <Text>Bottom Sheet Content</Text>
        </View>
      </BottomSheet>
    </View>
  );
};

export default App;
```

Bottom Sheet with FlatList

This code demonstrates how to use a FlatList inside the bottom sheet. This is useful for displaying a list of items within the bottom sheet.

```jsx
import React, { useRef } from 'react';
import { View, Text, Button, FlatList } from 'react-native';
import BottomSheet from '@gorhom/bottom-sheet';

const App = () => {
  const bottomSheetRef = useRef(null);
  const data = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);
  return (
    <View style={{ flex: 1 }}>
      <Button title="Open Bottom Sheet" onPress={() => bottomSheetRef.current?.expand()} />
      <BottomSheet ref={bottomSheetRef} snapPoints={[0, '50%', '100%']}>
        <FlatList
          data={data}
          keyExtractor={(item) => item}
          renderItem={({ item }) => (
            <View style={{ padding: 20 }}>
              <Text>{item}</Text>
            </View>
          )}
        />
      </BottomSheet>
    </View>
  );
};

export default App;
```

Other packages similar to @gorhom/bottom-sheet

reanimated-bottom-sheet

reanimated-bottom-sheet is another popular bottom sheet component for React Native. It is built on top of Reanimated and Gesture Handler libraries, providing smooth animations and gesture handling. Compared to @gorhom/bottom-sheet, it offers similar functionalities but may require more setup due to its dependencies on Reanimated and Gesture Handler.

react-native-modalize

react-native-modalize is a highly customizable modal component for React Native that can be used to create bottom sheets. It supports various features such as snapping points, custom handles, and more. While it offers similar functionalities to @gorhom/bottom-sheet, it is more focused on providing a general modal solution rather than just bottom sheets.

react-native-bottom-sheet-behavior

react-native-bottom-sheet-behavior is a library that provides bottom sheet behavior for React Native applications. It is inspired by the BottomSheetBehavior component in Android. This package is more Android-centric and may not offer the same level of customization and performance as @gorhom/bottom-sheet.

README

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
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

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

⚠️ 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? 😇

---