TrueSheet: how React Native's native bottom sheet handles sizing, architecture and the v3 to v4 split

Native platform APIs versus JavaScript-layer sheet overlays

Bottom sheet implementations in React Native divide into two categories: pure-JavaScript overlays that animate a view upward through the bridge, and components that call into the operating system's own presentation layer. TrueSheet belongs to the second category. Its README describes it as implemented in the native layer with zero JS hacks, meaning sizing behaviour, dismissal physics and native accessibility come from the platform rather than from userland animation code.

Native accessibility and screen reader support are built in, rather than layered on top of an animated view after the fact. TrueSheet builds on Fabric, React Native's New Architecture rendering pipeline. Sheet updates happen in the native layer rather than through a JavaScript bridge, and that design decision is what requires New Architecture as a hard dependency.

New Architecture as a hard prerequisite, and the compatibility matrix

Version 3.0 introduced a hard requirement: New Architecture must be enabled in the React Native project. Anyone running a project that cannot yet enable New Architecture cannot use v3 or later, and v2.x is the documented path for staying on the old bridge setup.

The compatibility table in the README sets out the exact ranges. TrueSheet 4.0 and above requires React Native 0.82 or newer and Expo SDK 55 or above. For v3.7 through v3.11, the supported range is React Native 0.81 to 0.86 and Expo SDK 54 to 57. Version 3.6 pairs with React Native 0.80 and Expo SDK 52 to 53. Beyond those React Native version requirements, Xcode 26.1 or later is a separate prerequisite listed for iOS development, sitting outside the npm install path entirely. That Xcode requirement does not surface until an iOS build runs, making it the kind of dependency that only appears in CI output and not during local setup.

Installing in Expo and bare React Native, and a first look at the component

Two install commands are documented by project type. For Expo managed workflow:

npx expo install @lodev09/react-native-true-sheet

For bare React Native, iOS pods need rebuilding after the package install:

yarn add @lodev09/react-native-true-sheet
cd ios && pod install

Both commands install v3. To install the v4 beta instead, append @beta to the Expo command:

npx expo install @lodev09/react-native-true-sheet@beta

A basic usage pattern imports the TrueSheet component and controls it through a ref:

import { TrueSheet } from "@lodev09/react-native-true-sheet"

const sheet = useRef<TrueSheet>(null)
const present = async () => {
  await sheet.current?.present()
}

return (
  <TrueSheet
    ref={sheet}
    detents={['auto', 1]}
  >
    <Button onPress={dismiss} title="Dismiss" />
  </TrueSheet>
)

The `present()` and `dismiss()` calls are async, so callers can await them to know when the animation completes. The `detents` prop takes an array where `'auto'` sizes the sheet to content height and `1` represents full-screen height. A migration guide at sheet.lodev09.com/migration covers upgrading between major versions.

How detents work, and what v4's synchronous layout changes

Detents define the heights a sheet snaps to. In v3, these are fixed positions: `'auto'` sizes to content height and a number between 0 and 1 is a fraction of screen height. The sheet moves between those positions, but the container does not resize in real time during a drag.

Version 4 changes the layout model. Content now resizes in the same frame as the sheet, a property v4's What's New section calls synchronous layout per detent. Dragging the sheet updates the container height continuously rather than snapping after the gesture ends. An added `scrollableRef` prop accepts a `ScrollView` or `FlatList` reference, wiring nested scroll behaviour, keyboard insets and the `auto` detent sizing together. Footers in v4 also shift: they occupy space below the content by default instead of overlapping it.

Side sheets for tablets, Liquid Glass on iOS 26, and web support

iPad and Android tablets get native side-sheet support, where the sheet attaches to the screen edge instead of sliding from the bottom, which suits larger displays better than a bottom-anchored presentation. Configuration lives at sheet.lodev09.com/guides/side-sheets.

On iOS 26 and later, TrueSheet supports Liquid Glass, the surface material introduced in that OS version. An Expo Blog post at expo.dev/blog/how-to-create-apple-maps-style-liquid-glass-sheets demonstrates the effect, and the project's guide at sheet.lodev09.com/guides/liquid-glass covers configuration. Adopting it requires running iOS 26.

Web support ships without additional configuration. A web-specific preview image in the repository shows a modal presentation in a browser window. The web guide lives at sheet.lodev09.com/guides/web. These three targets each have their own documentation page, and none of the configuration spills into the main TrueSheet props.

Keyboard handling, TrueSheetOverlay for stacked content, and React Navigation integration

Keyboard handling is built in and adjusts the sheet automatically when the on-screen keyboard appears or disappears; the guide at sheet.lodev09.com/guides/keyboard covers the specifics. Without built-in handling, text input fields inside a sheet often produce jumpy transitions when the keyboard opens, because the sheet height change and the keyboard avoidance mechanism run independently and fight each other.

For content that must render above the sheet itself, TrueSheetOverlay is a component that handles toasts, dialogs and other overlays without requiring FullWindowOverlay or Modal workarounds. Its guide is at sheet.lodev09.com/guides/overlays.

Navigation has two integration paths. A sheet navigator works with React Navigation, documented at sheet.lodev09.com/guides/navigation. For Expo Router, v4 adds a Sheet layout component importable from the /navigation/expo-router export path. Each integration is a separate entry in the package.json exports field, so only the integration you use is loaded.

v4 beta timeline, a version discrepancy in the working tree, and when v2.x applies

Version 4 was in beta as of 2026-10-06. The most recently published version is v4.0.0-beta.23, dated 2026-08-09. A detail worth checking before pinning to the main branch: the package.json in the repository shows 4.0.0-beta.24, one increment ahead of that published tag. The working tree has already bumped the version to beta.24, but that version has not yet been pushed to npm. Anyone installing @beta gets beta.23; the main branch source is already past it, so if you are watching specific changes in the working tree, the npm package and the repository head are out of sync.

For stable production use, v3.11.18 is the current stable build, published on 2026-10-02. It supports React Native 0.81 to 0.86 and Expo SDK 54 to 57. TrueSheet is MIT-licensed; source is at github.com/lodev09/react-native-true-sheet. Projects that cannot enable New Architecture at all have only one documented option: v2.x, which the README names directly as the fallback. The v4 migration guide at docs/docs/migration.mdx covers breaking changes for anyone upgrading.

Editorial conclusion

TrueSheet is the right choice when you need bottom sheets backed by platform presentation APIs rather than JavaScript animation code, and when your app already runs on New Architecture. Skip it if your project uses the old bridge architecture and cannot migrate: v2.x is the only documented path for apps that must stay there. Before adopting v4, accept the beta label and note that the package.json in the main branch shows 4.0.0-beta.24 while the latest stable version on npm is v3.11.18. For production use today, v3.11.18 is the current stable version, requiring React Native 0.81 at minimum.

Frequently asked questions

Official sources

1. License: MIT
2. lodev09/react-native-true-sheet on GitHub
3. Project website
4. README
5. Releases