Skip to main content

Troubleshooting

Blank Screen When Dismissing React Native Modal on iOS​

When presenting a TrueSheet on top of a React Native <Modal> and then dismissing the Modal (by setting visible={false}), the screen may go blank. This is a bug in React Native where dismissing a Modal that has another view controller presented on top of it only dismisses the topmost view controller, leaving the Modal in an inconsistent state.

Workaround:

Dismiss the sheet first before hiding the Modal:

const sheet = useRef<TrueSheet>(null)
const [modalVisible, setModalVisible] = useState(false)

const closeModal = async () => {
  await sheet.current?.dismiss()
  setModalVisible(false)
}
info

A fix has been submitted to React Native. See PR #55005.

Gesture Handler Not Working on Android​

If you're using react-native-gesture-handler inside the sheet and gestures are not working on Android, you need to wrap your sheet content with GestureHandlerRootView.

import { GestureHandlerRootView } from 'react-native-gesture-handler'

<TrueSheet>
  <GestureHandlerRootView style={{ flexGrow: 1 }}>
    {/* Your content with gestures */}
  </GestureHandlerRootView>
</TrueSheet>
warning

Use flexGrow: 1 instead of flex: 1 to avoid layout issues.

Learn more about gesture handler setup on Android.

Initial Present and Deep Linking​

On iOS, initialDetentIndex may not work when deep linking to a modal screen from a cold start. When navigating back to the home screen, the sheet won't present because the view wasn't attached to the correct window during the initial render.

Workaround:

Use useFocusEffect to present the sheet when the screen gains focus, conditioned on whether the initial present failed:

import { useFocusEffect } from '@react-navigation/native';
import { useCallback } from 'react';

function HomeScreen() {
  const sheet = useRef<TrueSheet>(null);
  const [didPresent, setDidPresent] = useState(false);

  useFocusEffect(
    useCallback(() => {
      if (!didPresent) {
        sheet.current?.present();
      }
    }, [didPresent])
  );

  return (
    <View>
      <TrueSheet
        ref={sheet}
        initialDetentIndex={0}
        onDidPresent={() => setDidPresent(true)}
      >
        {/* ... */}
      </TrueSheet>
    </View>
  );
}

Weird layout render​

The sheet does not have control over how React Native renders components and may lead to rendering issues. To resolve this, try to minimize the use of flex=1 in your content styles. Instead, use fixed height or employ flexGrow, flexBasis, etc., to manage your layout requirements.

Xcode and EAS Build Issues​

Xcode Version​

The package requires Xcode 26.1 or later. Background functionality may not work correctly with older versions. Check your Xcode version:

xcodebuild -version

EAS Build Configuration​

When using EAS Build, configure your eas.json to use a build image with Xcode 26.1+. Use "image": "latest" or choose from the available build images:

{
  "build": {
    "production": {
      "ios": {
        "image": "latest"
      }
    },
    "development": {
      "ios": {
        "image": "latest"
      }
    }
  }
}