Anh Tu Do

Posted on May 2

The Sheet for React Native: A Modular Sheet Framework

#reactnative #mobile

The Problem

There are various ways to present content to users on mobile, such as popups, dropdowns, bottom sheets, and center sheets. In most apps, these appear as modals, a focused layer that sits above the rest of the interface.

In React Native, the built-in Modal component achieves this. However, its API surface is limited and tightly coupled with native presentation behavior. Once you require customized behavior, complex gesture systems, or intricate interactions between multiple modals, you often find yourself fighting the framework.

Several libraries have emerged to fill this gap:

gorhom/react-native-bottom-sheet
ammarahm-ed/react-native-actions-sheet
lodev09/react-native-true-sheet

While I haven't tried every library available, I used gorhom/react-native-bottom-sheet extensively at my company. During that time, I frequently encountered bugs with limited documentation to guide me toward solutions or alternatives. Some of the most prominent issues included:

Z-index conflicts: Opening multiple bottom sheets simultaneously often led to incorrect stacking behavior.
Dynamic sizing: Auto-sizing did not work reliably, particularly when involving scroll views.
Jittery gestures: The sheet would occasionally "jump" while being dragged.
Keyboard handling: Managing focus and layout across different keyboard scenarios remained inconsistent.

I initially created wrappers around the library components to mitigate these issues, but they were merely band-aid solutions that didn't address the root causes.

A New Approach

Recently, as I became more involved in open source and learned more about library maintenance and releases, I decided to take a fresh look at this problem. I am building a new library from the ground up, designed with a flexible API and explicit handling of edge cases.

Feel free to check it out here: https://github.com/doanhtu07/react-native-the-sheet

The Mental Model

In this post, I want to share the mental model behind the library's design and the specific problems it aims to solve. The Sheet is a system comprising three separate layers:

Stack Item Layer
Presenter Layer
Content Layer

Stack Item Layer

This layer is responsible for registering the current sheet onto the stack. The stack generates a unique z-index based on the order of registration, ensuring that sheets are displayed in the correct order when multiple sheets are open simultaneously.

Presenter Layer

The presenter manages the general presentation logic. It always opens from 0% to 100% and closes from 100% to 0%. As you can imagine, this layer can move from bottom to top, left to right, or even diagonally.

This is the "secret sauce" behind supporting dynamic sizing by default. Because the presenter focuses on the transition, it doesn't need to know the content size beforehand; the content is free to size itself as needed.

Content Layer

This is the actual content you want to display. It can be a simple view with text or a complex component with gestures and animations, like a bottom sheet. You could even have a view centered on the screen, and it will work perfectly.

A Small Example

The Sheet can be used for various use cases, but in this example, I want to focus on bottom sheets. These are common requirements, but are difficult to implement correctly while handling all edge cases.

1. Wrap your app with the necessary providers

import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
import {
  SheetStackProvider,
  SheetKeyboardProvider,
  BottomSheetRegistryProvider,
} from "react-native-the-sheet";
import { PortalHost, PortalProvider } from "react-native-universe-portal";

export default function App() {
  return (
    <SafeAreaProvider>
      <SheetKeyboardProvider
        androidWindowSoftInputMode={/* Your app's Android window soft input mode */}
      >
        <SheetStackProvider debug>
          <PortalProvider>
            <BottomSheetRegistryProvider>
              <GestureHandlerRootView>
                {/* Your app content */}
                <PortalHost name="root" debug />
              </GestureHandlerRootView>
            </BottomSheetRegistryProvider>
          </PortalProvider>
        </SheetStackProvider>
      </SheetKeyboardProvider>
    </SafeAreaProvider>
  );
}

SafeAreaProvider: Required to calculate the true safe area height available for the sheet.
SheetKeyboardProvider: Handles keyboard interactions correctly on Android (specifically for non-edge-to-edge layouts, adjustResize, and adjustPan).
SheetStackProvider: Manages the stack of sheets and their relative z-indices.
PortalProvider: Teleports content to the correct place in the view hierarchy.
BottomSheetRegistryProvider: Allows you to read internal bottom sheet states using just a sheet ID.

2. Use components to construct the bottom sheet

In this sample, we create a simple bottom sheet featuring:

Dynamic sizing
Backdrop
Handle
Static content that is aware of pan gesture (using BottomSheetView)
- When you drag the handle or the content, the sheet will follow your finger

import { Fragment, useState } from "react";
import { Button, StyleSheet, Text, View } from "react-native";
import {
  Backdrop,
  BottomSheet,
  BottomSheetHandle,
  BottomSheetPresenter,
  BottomSheetProvider,
  BottomSheetView,
  SheetStackItem,
} from "react-native-the-sheet";
import { Portal } from "react-native-universe-portal";

export default function ExampleBottomSheetView() {
  const [isOpenA, setIsOpenA] = useState(false);

  const renderContent = () => {
    return (
      <Fragment>
        {Array.from({ length: 20 }).map((_, index) => (
          <Text key={index}>Item {index + 1}</Text>
        ))}
      </Fragment>
    );
  };

  return (
    <View style={styles.root}>
      <Text style={styles.header}>Example Bottom Sheet View</Text>

      <Button title="Open Sheet A" onPress={() => setIsOpenA(true)} />

      <Portal hostName="root">
        <SheetStackItem
          isOpen={isOpenA}
          close={() => setIsOpenA(false)}
          waitForFullyExit
          testID="sheetA"
        >
          <Backdrop />

          <BottomSheetPresenter>
            <BottomSheetProvider>
              <BottomSheet>
                <BottomSheetHandle />

                <BottomSheetView>
                  <Text>Sheet A</Text>
                  <Button
                    title="Close Sheet A"
                    onPress={() => setIsOpenA(false)}
                  />
                  {renderContent()}
                </BottomSheetView>
              </BottomSheet>
            </BottomSheetProvider>
          </BottomSheetPresenter>
        </SheetStackItem>
      </Portal>
    </View>
  );
}

// Styles

const styles = StyleSheet.create({
  header: {
    fontSize: 20,
    fontWeight: "500",
  },
  root: {
    flex: 1,
    gap: 8,
    padding: 16,
  },
});

Flexible API

As you might have noticed, you don't need to pass many props to these components. Most functionality is encapsulated within the components themselves, giving you the freedom to mix and layout them however you choose.

Of course, there are exceptions, but I encourage you to be creative. You might discover useful patterns that I haven't even thought of yet.

Also, this example only scratches the surface of the library's capabilities. There are many more components supporting various features. Check out the full list of components and their documentation here:

Conclusion

That's it for now! I hope this gives you a good overview of the library and the mental model behind it. If you have any questions, feel free to leave a comment or open an issue on the GitHub repo: https://github.com/doanhtu07/react-native-the-sheet.

I'm always looking for feedback and suggestions on new features to improve the library for everyone while keeping the API as simple and flexible as possible.

DEV Community