Cursor rule

1---
2alwaysApply: false
3---
4 
5## Use Native Navigators for Navigation
6 
7Always use native navigators instead of JS-based ones. Native navigators use
8platform APIs (UINavigationController on iOS, Fragment on Android) for better
9performance and native behavior.
10 
11**For stacks:** Use `@react-navigation/native-stack` or expo-router's default
12stack (which uses native-stack). Avoid `@react-navigation/stack`.
13 
14**For tabs:** Use `react-native-bottom-tabs` (native) or expo-router's native
15tabs. Avoid `@react-navigation/bottom-tabs` when native feel matters.
16 
17### Stack Navigation
18 
19**Incorrect (JS stack navigator):**
20 
21```tsx
22import { createStackNavigator } from '@react-navigation/stack'
23 
24const Stack = createStackNavigator()
25 
26function App() {
27  return (
28    <Stack.Navigator>
29      <Stack.Screen name='Home' component={HomeScreen} />
30      <Stack.Screen name='Details' component={DetailsScreen} />
31    </Stack.Navigator>
32  )
33}
34```
35 
36**Correct (native stack with react-navigation):**
37 
38```tsx
39import { createNativeStackNavigator } from '@react-navigation/native-stack'
40 
41const Stack = createNativeStackNavigator()
42 
43function App() {
44  return (
45    <Stack.Navigator>
46      <Stack.Screen name='Home' component={HomeScreen} />
47      <Stack.Screen name='Details' component={DetailsScreen} />
48    </Stack.Navigator>
49  )
50}
51```
52 
53**Correct (expo-router uses native stack by default):**
54 
55```tsx
56// app/_layout.tsx
57import { Stack } from 'expo-router'
58 
59export default function Layout() {
60  return <Stack />
61}
62```
63 
64### Tab Navigation
65 
66**Incorrect (JS bottom tabs):**
67 
68```tsx
69import { createBottomTabNavigator } from '@react-navigation/bottom-tabs'
70 
71const Tab = createBottomTabNavigator()
72 
73function App() {
74  return (
75    <Tab.Navigator>
76      <Tab.Screen name='Home' component={HomeScreen} />
77      <Tab.Screen name='Settings' component={SettingsScreen} />
78    </Tab.Navigator>
79  )
80}
81```
82 
83**Correct (native bottom tabs with react-navigation):**
84 
85```tsx
86import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'
87 
88const Tab = createNativeBottomTabNavigator()
89 
90function App() {
91  return (
92    <Tab.Navigator>
93      <Tab.Screen
94        name='Home'
95        component={HomeScreen}
96        options={{
97          tabBarIcon: () => ({ sfSymbol: 'house' }),
98        }}
99      />
100      <Tab.Screen
101        name='Settings'
102        component={SettingsScreen}
103        options={{
104          tabBarIcon: () => ({ sfSymbol: 'gear' }),
105        }}
106      />
107    </Tab.Navigator>
108  )
109}
110```
111 
112**Correct (expo-router native tabs):**
113 
114```tsx
115// app/(tabs)/_layout.tsx
116import { NativeTabs } from 'expo-router/unstable-native-tabs'
117 
118export default function TabLayout() {
119  return (
120    <NativeTabs>
121      <NativeTabs.Trigger name='index'>
122        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
123        <NativeTabs.Trigger.Icon sf='house.fill' md='home' />
124      </NativeTabs.Trigger>
125      <NativeTabs.Trigger name='settings'>
126        <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
127        <NativeTabs.Trigger.Icon sf='gear' md='settings' />
128      </NativeTabs.Trigger>
129    </NativeTabs>
130  )
131}
132```
133 
134On iOS, native tabs automatically enable `contentInsetAdjustmentBehavior` on the
135first `ScrollView` at the root of each tab screen, so content scrolls correctly
136behind the translucent tab bar. If you need to disable this, use
137`disableAutomaticContentInsets` on the trigger.
138 
139### Prefer Native Header Options Over Custom Components
140 
141**Incorrect (custom header component):**
142 
143```tsx
144<Stack.Screen
145  name='Profile'
146  component={ProfileScreen}
147  options={{
148    header: () => <CustomHeader title='Profile' />,
149  }}
150/>
151```
152 
153**Correct (native header options):**
154 
155```tsx
156<Stack.Screen
157  name='Profile'
158  component={ProfileScreen}
159  options={{
160    title: 'Profile',
161    headerLargeTitleEnabled: true,
162    headerSearchBarOptions: {
163      placeholder: 'Search',
164    },
165  }}
166/>
167```
168 
169Native headers support iOS large titles, search bars, blur effects, and proper
170safe area handling automatically.
171 
172### Why Native Navigators
173 
174- **Performance**: Native transitions and gestures run on the UI thread
175- **Platform behavior**: Automatic iOS large titles, Android material design
176- **System integration**: Scroll-to-top on tab tap, PiP avoidance, proper safe
177  areas
178- **Accessibility**: Platform accessibility features work automatically
179 
180Reference:
181 
182- [React Navigation Native Stack](https://reactnavigation.org/docs/native-stack-navigator)
183- [React Native Bottom Tabs with React Navigation](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-react-navigation)
184- [React Native Bottom Tabs with Expo Router](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-expo-router)
185- [Expo Router Native Tabs](https://docs.expo.dev/router/advanced/native-tabs)
186