0
# Static Navigation
1

2
Utilities for creating navigation structures from static configuration objects, enabling declarative navigation setup and automatic path configuration generation.
3

4
## Capabilities
5

6
### createComponentForStaticNavigation
7

8
Create a React component that renders a navigator based on static configuration, enabling declarative navigation setup.
9

10
```typescript { .api }
11
/**
12
 * Create a navigation component from static configuration
13
 * @param tree - Static navigation configuration object
14
 * @param displayName - Component display name for React DevTools
15
 * @returns React component that renders the configured navigation
16
 */
17
function createComponentForStaticNavigation<T extends StaticNavigation<any, any, any>>(
18
  tree: T,
19
  displayName?: string
20
): React.ComponentType<{}>;
21

22
interface StaticNavigation<
23
  ScreenOptions extends {},
24
  EventMap extends EventMapBase,
25
  NavigatorID extends string | undefined
26
> {
27
  /** Configuration for screens in this navigator */
28
  screens: StaticConfigScreens<any, ScreenOptions, EventMap>;
29
  /** Navigator configuration */
30
  config?: StaticConfig<ScreenOptions, EventMap, NavigatorID>;
31
  /** Groups configuration */
32
  groups?: Record<string, StaticConfigGroup<any, ScreenOptions>>;
33
}
34

35
interface StaticConfig<
36
  ScreenOptions extends {},
37
  EventMap extends EventMapBase,
38
  NavigatorID extends string | undefined
39
> {
40
  /** Navigator ID for getParent references */
41
  navigationId?: NavigatorID;
42
  /** Initial route name */
43
  initialRouteName?: string;
44
  /** Default screen options */
45
  screenOptions?: ScreenOptions;
46
  /** Screen layout component */
47
  screenLayout?: React.ComponentType<any>;
48
  /** Event listeners */
49
  screenListeners?: any;
50
}
51

52
type StaticConfigScreens<
53
  ParamList extends ParamListBase,
54
  ScreenOptions extends {},
55
  EventMap extends EventMapBase
56
> = {
57
  [K in keyof ParamList]: StaticScreenProps<ParamList, K, ScreenOptions, EventMap>;
58
};
59

60
interface StaticScreenProps<
61
  ParamList extends ParamListBase,
62
  RouteName extends keyof ParamList,
63
  ScreenOptions extends {},
64
  EventMap extends EventMapBase
65
> {
66
  /** Screen component to render */
67
  component?: React.ComponentType<any>;
68
  /** Lazy-loaded screen component */
69
  getComponent?: () => React.ComponentType<any>;
70
  /** Screen options */
71
  options?: ScreenOptions;
72
  /** Initial parameters */
73
  initialParams?: ParamList[RouteName];
74
  /** Event listeners */
75
  listeners?: any;
76
  /** Screen ID function */
77
  getId?: ({ params }: { params: ParamList[RouteName] }) => string | undefined;
78
  /** Navigation key */
79
  navigationKey?: string;
80
  /** Screen layout */
81
  layout?: React.ComponentType<any>;
82
  /** Children for nested navigation */
83
  children?: StaticNavigation<ScreenOptions, EventMap, any>;
84
}
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import { createComponentForStaticNavigation } from "@react-navigation/core";
91

92
// Define static navigation configuration
93
const staticConfig = {
94
  screens: {
95
    Home: {
96
      component: HomeScreen,
97
      options: { title: 'Welcome' }
98
    },
99
    Profile: {
100
      component: ProfileScreen,
101
      options: { title: 'Profile' },
102
      initialParams: { tab: 'info' }
103
    },
104
    Settings: {
105
      getComponent: () => import('./SettingsScreen'),
106
      options: { title: 'Settings' }
107
    }
108
  },
109
  config: {
110
    initialRouteName: 'Home',
111
    screenOptions: {
112
      headerStyle: { backgroundColor: '#6200ee' },
113
      headerTintColor: 'white'
114
    }
115
  }
116
};
117

118
// Create navigation component
119
const AppNavigator = createComponentForStaticNavigation(
120
  staticConfig,
121
  'AppNavigator'
122
);
123

124
// Use in app
125
function App() {
126
  return (
127
    <BaseNavigationContainer>
128
      <AppNavigator />
129
    </BaseNavigationContainer>
130
  );
131
}
132

133
// Nested navigation example
134
const nestedConfig = {
135
  screens: {
136
    Main: {
137
      children: {
138
        screens: {
139
          Home: { component: HomeScreen },
140
          Feed: { component: FeedScreen }
141
        },
142
        config: { initialRouteName: 'Home' }
143
      }
144
    },
145
    Profile: {
146
      component: ProfileScreen
147
    }
148
  },
149
  config: {
150
    initialRouteName: 'Main'
151
  }
152
};
153

154
const NestedNavigator = createComponentForStaticNavigation(
155
  nestedConfig,
156
  'NestedNavigator'
157
);
158

159
// Groups configuration
160
const groupedConfig = {
161
  screens: {
162
    Home: {
163
      component: HomeScreen,
164
      options: { title: 'Home' }
165
    },
166
    Profile: {
167
      component: ProfileScreen, 
168
      options: { title: 'Profile' }
169
    },
170
    Settings: {
171
      component: SettingsScreen,
172
      options: { title: 'Settings' }
173
    }
174
  },
175
  groups: {
176
    user: {
177
      screens: ['Profile', 'Settings'],
178
      screenOptions: {
179
        headerStyle: { backgroundColor: 'blue' }
180
      }
181
    }
182
  },
183
  config: {
184
    initialRouteName: 'Home'
185
  }
186
};
187

188
const GroupedNavigator = createComponentForStaticNavigation(
189
  groupedConfig,
190
  'GroupedNavigator'
191
);
192
```
193

194
### createPathConfigForStaticNavigation
195

196
Generate path configuration from static navigation configuration for deep linking support.
197

198
```typescript { .api }
199
/**
200
 * Create path configuration from static navigation for deep linking
201
 * @param tree - Static navigation configuration
202
 * @param options - Additional configuration options
203
 * @param auto - Whether to automatically generate paths
204
 * @returns Path configuration object for linking
205
 */
206
function createPathConfigForStaticNavigation(
207
  tree: StaticNavigation<any, any, any>,
208
  options?: { initialRouteName?: string },
209
  auto?: boolean
210
): PathConfigMap<any>;
211
```
212

213
**Usage Examples:**
214

215
```typescript
216
import { 
217
  createPathConfigForStaticNavigation,
218
  createComponentForStaticNavigation
219
} from "@react-navigation/core";
220

221
// Static navigation with path hints
222
const navigationConfig = {
223
  screens: {
224
    Home: {
225
      component: HomeScreen,
226
      // Path configuration can be inferred from screen name
227
    },
228
    Profile: {
229
      component: ProfileScreen,
230
      // Will generate path: '/Profile'
231
    },
232
    UserDetails: {
233
      component: UserDetailsScreen,
234
      // Will generate path: '/UserDetails'
235
    }
236
  },
237
  config: {
238
    initialRouteName: 'Home'
239
  }
240
};
241

242
// Create path configuration automatically
243
const pathConfig = createPathConfigForStaticNavigation(
244
  navigationConfig,
245
  { initialRouteName: 'Home' },
246
  true // Auto-generate paths
247
);
248

249
// Result path config:
250
// {
251
//   Home: '',
252
//   Profile: 'Profile',
253
//   UserDetails: 'UserDetails'
254
// }
255

256
// Manual path configuration with parameters
257
const manualConfig = {
258
  screens: {
259
    Home: { component: HomeScreen },
260
    Profile: { 
261
      component: ProfileScreen,
262
      // Add path metadata for parameter extraction
263
      linkingPath: '/user/:userId'
264
    },
265
    Settings: { 
266
      component: SettingsScreen,
267
      linkingPath: '/settings/:section?'
268
    }
269
  }
270
};
271

272
const manualPathConfig = createPathConfigForStaticNavigation(manualConfig);
273

274
// Use with navigation container
275
function App() {
276
  const Navigator = createComponentForStaticNavigation(navigationConfig);
277
  
278
  return (
279
    <BaseNavigationContainer
280
      linking={{
281
        prefixes: ['https://myapp.com/', 'myapp://'],
282
        config: {
283
          screens: pathConfig
284
        }
285
      }}
286
    >
287
      <Navigator />
288
    </BaseNavigationContainer>
289
  );
290
}
291

292
// Complex nested navigation with paths
293
const complexConfig = {
294
  screens: {
295
    Auth: {
296
      children: {
297
        screens: {
298
          Login: { component: LoginScreen },
299
          Register: { component: RegisterScreen }
300
        }
301
      }
302
    },
303
    Main: {
304
      children: {
305
        screens: {
306
          Home: { component: HomeScreen },
307
          Profile: { component: ProfileScreen }
308
        }
309
      }
310
    }
311
  }
312
};
313

314
const complexPathConfig = createPathConfigForStaticNavigation(
315
  complexConfig,
316
  undefined,
317
  true
318
);
319

320
// Result:
321
// {
322
//   Auth: {
323
//     screens: {
324
//       Login: 'Login',
325
//       Register: 'Register'
326
//     }
327
//   },
328
//   Main: {
329
//     screens: {
330
//       Home: 'Home', 
331
//       Profile: 'Profile'
332
//     }
333
//   }
334
// }
335
```
336

337
### Static Navigation Configuration Types
338

339
Core types for static navigation configuration.
340

341
```typescript { .api }
342
/**
343
 * Group configuration for organizing screens
344
 */
345
interface StaticConfigGroup<
346
  ParamList extends ParamListBase,
347
  ScreenOptions extends {}
348
> {
349
  /** Screen names that belong to this group */
350
  screens?: (keyof ParamList)[];
351
  /** Options applied to all screens in the group */
352
  screenOptions?: ScreenOptions;
353
  /** Layout component for screens in the group */
354
  screenLayout?: React.ComponentType<any>;
355
  /** Navigation key for the group */
356
  navigationKey?: string;
357
}
358

359
/**
360
 * Parameter list type for static navigation
361
 */
362
type StaticParamList<T extends StaticNavigation<any, any, any>> = 
363
  T extends StaticNavigation<any, any, any> 
364
    ? T['screens'] extends StaticConfigScreens<infer P, any, any>
365
      ? P
366
      : ParamListBase
367
    : ParamListBase;
368

369
/**
370
 * Screen props type for static navigation screens
371
 */
372
type StaticScreenProps<
373
  Navigation extends StaticNavigation<any, any, any>,
374
  RouteName extends keyof Navigation['screens']
375
> = {
376
  navigation: NavigationProp<StaticParamList<Navigation>, RouteName>;
377
  route: RouteProp<StaticParamList<Navigation>, RouteName>;
378
};
379
```
380

381
**Usage Examples:**
382

383
```typescript
384
// Type-safe static navigation configuration
385
interface AppParamList {
386
  Home: undefined;
387
  Profile: { userId: string };
388
  Settings: { section?: string };
389
}
390

391
const typedConfig: StaticNavigation<
392
  { title?: string; headerShown?: boolean },
393
  {},
394
  undefined
395
> = {
396
  screens: {
397
    Home: {
398
      component: HomeScreen,
399
      options: { title: 'Welcome' }
400
    },
401
    Profile: {
402
      component: ProfileScreen,
403
      options: { title: 'Profile' },
404
      initialParams: { userId: 'default' }
405
    },
406
    Settings: {
407
      component: SettingsScreen,
408
      options: { title: 'Settings' }
409
    }
410
  } satisfies StaticConfigScreens<AppParamList, any, any>,
411
  config: {
412
    initialRouteName: 'Home',
413
    screenOptions: { headerShown: true }
414
  }
415
};
416

417
// Type-safe screen components
418
function ProfileScreen({ 
419
  navigation, 
420
  route 
421
}: StaticScreenProps<typeof typedConfig, 'Profile'>) {
422
  // route.params is typed as { userId: string }
423
  const { userId } = route.params;
424
  
425
  return (
426
    <View>
427
      <Text>User ID: {userId}</Text>
428
      <Button
429
        title="Go to Settings"
430
        onPress={() => navigation.navigate('Settings', { section: 'account' })}
431
      />
432
    </View>
433
  );
434
}
435

436
// Groups with type safety
437
const groupedTypedConfig = {
438
  ...typedConfig,
439
  groups: {
440
    user: {
441
      screens: ['Profile', 'Settings'] as const,
442
      screenOptions: {
443
        headerStyle: { backgroundColor: '#007AFF' }
444
      }
445
    }
446
  }
447
};
448
```
449

450
### Integration with Navigation Container
451

452
Using static navigation with the navigation container and linking configuration.
453

454
```typescript { .api }
455
// Complete app setup with static navigation and deep linking
456
function createAppWithStaticNavigation() {
457
  const navigationConfig = {
458
    screens: {
459
      Home: { component: HomeScreen },
460
      Profile: { component: ProfileScreen },
461
      Settings: { component: SettingsScreen }
462
    },
463
    config: {
464
      initialRouteName: 'Home'
465
    }
466
  };
467

468
  const Navigator = createComponentForStaticNavigation(
469
    navigationConfig,
470
    'AppNavigator'
471
  );
472

473
  const pathConfig = createPathConfigForStaticNavigation(
474
    navigationConfig,
475
    { initialRouteName: 'Home' },
476
    true
477
  );
478

479
  return function App() {
480
    return (
481
      <BaseNavigationContainer
482
        linking={{
483
          prefixes: ['myapp://'],
484
          config: { screens: pathConfig }
485
        }}
486
      >
487
        <Navigator />
488
      </BaseNavigationContainer>
489
    );
490
  };
491
}
492

493
const App = createAppWithStaticNavigation();
494
```