The Sheet for React Native: A Modular Sheet Framework

Source: Dev.to

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:

I initially created wrappers around the library components to mitigate these issues, but they were merely band‑aids that didn’t address the root causes.

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.

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 System

The Sheet is a system comprising three separate layers:

1. Stack Item Layer – Registers 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.

2. Presenter Layer – 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.

3. Content Layer – 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.

The Sheet can be used for various use cases, but in this example I’ll focus on bottom sheets—a common requirement that is difficult to implement correctly while handling all edge cases.

Example Setup

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 (
    <GestureHandlerRootView>
      <SafeAreaProvider>
        <SheetKeyboardProvider>
          <SheetStackProvider>
            <PortalProvider>
              {/* Your app content */}
            </PortalProvider>
          </SheetStackProvider>
        </SheetKeyboardProvider>
      </SafeAreaProvider>
    </GestureHandlerRootView>
  );
}

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 gestures (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 = () => (
    <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" onPress={() => setIsOpenA(true)} />

      <SheetStackItem
        isOpen={isOpenA}
        onClose={() => setIsOpenA(false)}
        waitForFullyExit
        testID="sheetA"
      >
        <BottomSheetProvider>
          <Backdrop />
          <BottomSheetPresenter>
            <BottomSheet>
              <BottomSheetHandle />
              <BottomSheetView>{renderContent()}</BottomSheetView>
            </BottomSheet>
          </BottomSheetPresenter>
        </BottomSheetProvider>
      </SheetStackItem>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { flex: 1, justifyContent: "center", alignItems: "center" },
  header: { fontSize: 18, marginBottom: 12 },
});

Explanation of the Components

TL;DR

• Three‑layer architecture (Stack → Presenter → Content) gives you reliable z‑index handling, flexible animation directions, and true dynamic sizing.
• The SheetStackProvider + SheetStackItem take care of ordering multiple sheets.
• The Presenter abstracts transition logic, so the content never needs to know its own size ahead of time.
• The Content layer can be any React component, from a simple text list to a fully‑featured gesture‑driven view.

Give the library a spin and let me know what you think!

<SheetStackItem
  isOpen={isOpenA}
  onClose={() => setIsOpenA(false)}
  testID="sheetA"
>
  <BottomSheetProvider>
    <Backdrop />
    <BottomSheetPresenter>
      <BottomSheet>
        <BottomSheetHandle />
        <BottomSheetView>{renderContent()}</BottomSheetView>
      </BottomSheet>
    </BottomSheetPresenter>
  </BottomSheetProvider>
</SheetStackItem>

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

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:

• 📚 Architecture Docs
• 📚 API Docs

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.