Picking native-stack in React Navigation—and Building a Typed Setup Around It

Your stack navigator works fine in development. Then you run the app on a mid-range Android phone, push a screen with a heavy list on it, and the transition stutters because the animation is being driven frame-by-frame on the JavaScript thread—the same thread your list is re-rendering on. That is the moment most teams look at @react-navigation/native-stack instead of @react-navigation/stack. The short version: native-stack moves transitions onto platform primitives (UINavigationController on iOS, Fragments on Android), so animations keep running even when JS is busy. The trade-off is less customization. This post is about making that call deliberately and structuring a typed, maintainable setup around whichever you pick.

What native-stack actually changes

With the JS stack navigator, React Navigation computes transition frames in JavaScript. If the JS thread is blocked—parsing a large API response, rendering a new screen, running a synchronous loop—frames drop and the user sees a janky push. With native-stack, the platform owns the transition. You also get platform-faithful behavior for free: iOS large titles that collapse on scroll, the interactive swipe-back gesture, and standard push/pop animations that match the rest of the OS.

The cost is control. The JS stack exposes deep customization of gestures, header rendering, and transition timing curves. Native-stack exposes what the platform exposes. If your design calls for a bespoke shared-element-style transition or a heavily custom header, native-stack will fight you, and the JS stack (or a different animation approach) may be the right answer. Decide based on your design requirements, not on benchmarks alone.

One param list, typed everywhere

Whichever navigator you choose, the highest-leverage structural decision is a single source of truth for routes and their parameters. Define a param-list type and derive everything else from it:

// navigation/types.ts
export type RootStackParamList = {
  Auth: undefined;          // nested navigator, no params
  Main: undefined;          // nested tab navigator
  OrderDetail: { orderId: string };
  EditProfile: { fromSettings?: boolean };
};

// App.tsx (requires @react-navigation/native-stack installed)
import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator<RootStackParamList>();

function RootNavigator() {
  return (
    <Stack.Navigator screenOptions={{ headerLargeTitle: true }}>
      <Stack.Screen name="Auth" component={AuthStack}
        options={{ headerShown: false }} />
      <Stack.Screen name="Main" component={MainTabs}
        options={{ headerShown: false }} />
      <Stack.Screen name="OrderDetail" component={OrderDetailScreen}
        options={({ route }) => ({ title: `Order ${route.params.orderId}` })} />
      <Stack.Screen name="EditProfile" component={EditProfileScreen}
        options={{ presentation: 'modal', title: 'Edit profile' }} />
    </Stack.Navigator>
  );
}

Now a call like navigation.navigate('OrderDetail', { orderId: order.id }) is checked at compile time. Pass a number, misspell the route, or omit orderId, and TypeScript fails the build. To verify this works, deliberately write navigation.navigate('OrderDetail', { orderId: 42 }) and confirm tsc --noEmit errors—then revert it. Note the limits: this typing says nothing about runtime deep links. A URL like myapp://order/abc arrives as strings, so validate and coerce params at the screen boundary before using them.

Keep options close to their screens

A common failure mode is screenOptions sprawl: every screen's quirks piled onto the navigator until nobody knows which option applies where. A workable rule: global screenOptions holds only true defaults (header tint, large titles, gesture enablement), and anything screen-specific—title, presentation: 'modal', headerShown: false—lives on the Stack.Screen registration itself, as in the example above. Nesting helps the same way: an auth stack and a main tab navigator inside one root stack lets you gate unauthenticated users at one boundary and keeps deep-link config organized per section.

The trade-offs worth writing down

• Not drop-in interchangeable. Option names, events, and defaults differ between the two navigators and across React Navigation major versions. Migrating screen-by-screen while mixing both stacks invites subtle behavioral bugs—migrate one navigator tree at a time.
• Header customization is narrower. If your design system needs a fully custom animated header, prototype it against native-stack early before committing.
• Verify on hardware. Run on a physical iOS and Android device: check swipe-back, large-title collapse, and modal presentation. Then use the React Native performance monitor while pushing a heavy screen to confirm transitions stay smooth under JS load—that is the whole reason for the switch.

The actionable takeaway: default to native-stack unless you have a concrete transition or header requirement it cannot express, centralize your param list in one type, and keep screen options next to their screens. Check exact option names against the major version you have installed before copying any of this into production.