Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

NativeViewGestureHandler must be used as a descendant of GestureHandlerRootView

ErrorError: NativeViewGestureHandler must be used as a descendant of GestureHandlerRootView. Otherwise the gestures will not be recognized.

Short answer

react-native-gesture-handler only recognises gestures inside GestureHandlerRootView. The error means a gesture component renders outside it. Wrap the whole app (or the navigator) in one root view, keep flex 1 in any custom style, and wrap screens separately if a navigator still fails.

  • Applies to react-native-gesture-handler 2.x, Expo SDK 5x, React Native 0.7x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find where the app root is rendered (App.tsx, or app/_layout.tsx with Expo Router) and check whether a GestureHandlerRootView surrounds everything.

    grep -rn "GestureHandlerRootView" --include=*.tsx --include=*.js . --exclude-dir=node_modules
  2. 2Match what you see, then jump to its fix

    1. 1The grep above returns nothingNo GestureHandlerRootView at the app rootFix
    2. 2The error is gone but the screen is blankThe root view has a custom style without flex: 1Fix
    3. 3Most screens work, one throws the errorThe root view is wrapped around the app but not around the failing screenFix

What does the error look like?

  • Error: NativeViewGestureHandler must be used as a descendant of GestureHandlerRootView. Otherwise the gestures will not be recognized.

Cause 1 of 3

No GestureHandlerRootView at the app root

1Check

Gestures are recognised only inside this view, so a gesture component with no root view above it raises the error.

grep -n "react-native-gesture-handler" package.json

2Fix

Wrap the root of the app. With Expo Router, wrap the Stack in the root layout.

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

export default function App() {
  return (
    <GestureHandlerRootView>
      <ActualApp />
    </GestureHandlerRootView>
  );
}

3Verify

Reload the app. The red screen should be gone and swipes or drags should work.

npx expo start --clear

Confirmed by docs.swmansion.com

Did this fix it?

Cause 2 of 3

The root view has a custom style without flex: 1

1Check

A style prop replaces the default. Without flex 1 the view has no height.

grep -rn -B1 -A1 "<GestureHandlerRootView" --include=*.tsx --include=*.js . --exclude-dir=node_modules

2Fix

Add flex: 1 to the custom style.

<GestureHandlerRootView style={{ flex: 1, backgroundColor: '#fff' }}>
  <ActualApp />
</GestureHandlerRootView>

3Verify

The app renders again.

npx expo start --clear

Confirmed by docs.swmansion.com

Did this fix it?

Cause 3 of 3

The root view is wrapped around the app but not around the failing screen

1Check

With a navigation library, wrapping the navigator is usually enough. Nested root views are ignored in favour of the top one, so a second wrapper elsewhere will not help.

grep -rn "GestureHandlerRootView" --include=*.tsx --include=*.js app src 2>/dev/null

2Fix

Wrap the navigator once. If gestures still fail under it, wrap each screen component too.

function Screen() {
  return (
    <GestureHandlerRootView>
      <ScreenContent />
    </GestureHandlerRootView>
  );
}

3Verify

Open the failing screen directly.

npx expo start --clear

Confirmed by docs.swmansion.com

Did this fix it?

How do I stop it coming back?

  • Wrap the app once, at the true root, when you add the library.
  • Install with npx expo install so the version matches your SDK.
  • Keep flex: 1 in every custom root view style.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

Expo app never leaves the splash screen

App shows the splash screen forever and no error appears

After SplashScreen.preventAutoHideAsync() the splash stays until you hide it yourself.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.