react-native-ios-navigator

A native wrapper component around UINavigationController for react-native.

🚧⚠️ Library WIP ⚠️🚧

• Currently in development... 😅 (See TODO.md for current progress).
• The documentation is incomplete (some parts/sections are marked as TBA i.e. "to be added").
• Some of the links in the documentation are broken (i.e. the URL points to PLACE_HOLDER_LINK).

Quick Links

😌💬 Hey there, if you're just checking this library out, I recommend jumping to the Showcase, Tests, and Demos section (It has a bunch of gifs showing all the various features).

A. Introduction

Before you use this library, please first consider looking at react-navigation, react-native-navigation, and react-router. They offer more features, are battle-tested, well maintained, and most importantly: cross-platform. This library is more of a personal pet project 😌.

A.1. Motivation

Expose Everything

This is a wrapper library, so the goal is (for better, or for worse) to expose almost everything to react-native.

I tried to expose, in some way or another, all the ways the UINavigationController, UINavigationBar, and UIViewController could be configured and customized. Unfortunately, this means that the API + documentation is a little dense/complex, and might be a little bit confusing to non-iOS developers (so I tried to include as much explanations, examples + gifs and images as I could).

Resurrecting NavigatorIOS

Basically, react-native deprecated the built-in NavigatorIOS component starting on version 0.58.

One thing that I liked about NavigatorIOS is that it behaved like any regular old <View/> component. Which is fun since you can just plop it down anywhere in your app, and it'll just "work" (this included the weird quirk of having multiple navigators 🤷‍♀️).

📝 Notes

• Modal support is handled via react-native-ios-modal (WIP)
• Adding menu's/submenu's in the navigation bar is handled via react-native-ios-context-menu (WIP)

A.2. Features

💡 Tip: You can also just browse through the gifs/images in the Showcase, Tests, and Demos section.

• Support for using native routes (e.g. UIViewController). Allows you to combine js/react routes and native routes together.
  • Support for controlling the navigator from native/swift-side (e.g. pushing routes, etc.)
  • Support for passing data (i.e. routeProps) between native and JS/React routes.

• Support for multiple initial react/native routes (useful for state-restoration, e.g. restoring the navigation stack on app startup).
• Support for using custom transitions (e.g. crossfade, slide, flip, etc).
• Support for customizing the navigation bar either through the "legacy" API (iOS 11 and below), or the newer appearance API (iOS 13+).
  • This includes per-route customizations using either the "legacy" or "appearance" modes.
  • Support for:
    • Using routes with a UISearchBar in the navigation bar.
    • Using either custom react components or standard navigation bar controls (e.g. buttons, text, icons) for the navigation bar items (e.g. navigation bar title, left items, right items).
    • Customizing the font style of the navigation bar title + large title.
    • Per-route navigation bar visibility and status bar style.
    • Customize the navigation bar tint, background color, background image, back indicator, blur effects, shadow, etc.
    • Support for generating images (e.g. solid colors, gradients, rounded rects, etc) that can be used as the navigation bar background, navigation bar items... basically, anywhere that accepts an image.
    • Etc.

• Exposes almost all of the UINavigationController/UIViewController-related events.
• Exposes all of the things that can be configured in the view controller's UINavigationItem (title, prompt, largeTitleDisplayMode, backBarButtonItem, etc).
• Etc.

B. Installation

# install via npm...
npm install react-native-ios-navigator

# or install via yarn.
yarn add react-native-ios-navigator

# then run pod install (uses auto-linking)
cd ios && pod install

📝 Note: This library is written in swift, so if you're having troubles building your project, try adding an empty swift file so that Xcode will generate a bridging-header.h file for your project.

Additional Setup

In your project's Info.plist file, set the "View controller-based status bar appearance" key from NO to YES. Toggling this property allows you to set the status bar style on a per-route basis.

Troubleshooting

The following build errors can usually be resolved by adding an empty swift file:

However, the older versions of the react-native template (e.g. 0.63 and below) hard codes the swift library search paths to use swift 5.0 (which causes the linker to mismatch the swift system libraries bundled with Xcode + iOS version). To fix this issue, just remove the following entries from the project config's library search path:

Versions

C. Basic Usage

This snippet is an excerpt from the Navigation Hello World section.

import * as React from 'react';
import { SafeAreaView, TouchableOpacity, Text } from 'react-native';
import { NavigatorView } from 'react-native-ios-navigator';

// Route to show in the navigator
function ExampleRoute(props){
  return (
    <SafeAreaView>
      <TouchableOpacity onPress={() => {
        props.navigation.push({
          routeKey: 'routeA'
        });
      }}>
        <Text> Push: 'RouteA' </Text>
      </TouchableOpacity>
    </SafeAreaView>
  );
};

export function App() {
  return(
    <NavigatorView
      initialRoutes={[{routeKey: 'routeA'}]}
      routes={{
        routeA: {
          renderRoute: () => (
            <ExampleRoute/>
          ),
        }
      }}
    />
  );
};

D. Documentation

💡 Tip: Most of the time, when a type or component is mentioned, you can click it to jump to that item in the README (or its declaration in the source code).

D.1. Components

D.1.1. NavigatorView Component

This component is a wrapper around UINavigationController, and as such, it also facilitates navigation in a stack-like manner (where in routes are "pushed" and "popped" in and out of the navigation stack). Only one route can be shown at a given time. However it is possible to have multiple NavigatorView instances at the same time.

• Each instance will have their own separate navigation stack, allowing you to show multiple routes at once.
• But do note that the 1st instance will always be treated as the "root" navigation controller, and subsequently, it’ll become responsible for handling things like setting the color of the status bar, etc.

Internally, each NavigatorView component corresponds to a UINavigationController instance, and conversely, each route in the navigation stack corresponds to a UIViewController instance.

• The “route content” (i.e. the element returned from a route’s renderRoute function) gets wrapped inside a view controller instance.
• That view controller is then sent off to the UINavigationController.

Each route has a corresponding RouteOptions object associated with it. This object is used internally to configure various aspects of the UINavigationController, UINavigationBar, UINavigationItem, UIViewController, etc.

NavigatorView Component: Props

NavigatorView General Props

NavigatorView Render Props

NavigatorView Event Props

NavigatorView Component: Properties/Methods

NavigatorView General/Misc. Methods

NavigatorView Navigation Commands

Listed in this section are commands that can be called to control the navigator (e.g. like showing or hiding a route, replacing a route in the navigation stack, etc). Unless specified otherwise, the commands listed here are really just invoking UINavigationController.setViewControllers internally in the native side.

• The navigation commands are asynchronous, and as such, they will return a promise that resolves once the command is completed.
• Due to timing related issues, the NavigatorView internally has a command queue, as such, only one command can be executed at a given time.
• So for example if you call push, then call pop immediately (i.e. not waiting for push to complete first before calling pop), they will always be executed in that order (i.e. it will always wait for the previous command to complete).

NavigatorView Convenience Navigation Commands

These are basically "presets" to existing navigation commands i.e. it uses the existing navigation commands available to provide shortcuts to common navigation actions for convenience.

D.1.2. RouteViewPortal Component

The purpose of this component is to allow for the customization of a route after it's been pushed (e.g. like dynamically overriding/updating a route's RouteOptions, or rendering custom components to show inside the navigation bar, etc).

📝 Note: The reason why this component has the "portal" suffix is because it's "transporting" things like the route options and the render props somewhere else.

This component is meant to be used inside a route (i.e. it must be used inside the renderRoute function in the NavigatorView.routes prop). This is because internally, this component relies on react context to communicate to the parent route container (i.e. NavigatorRouteView) component.

For some extra background info, the NavigatorRouteView component is responsible for:

• A. rendering the component returned by renderRoute,
• B. managing the route's lifecycle, and
• C. communicating with the native views/modules, etc.

As such this component doesn't actually render anything directly, it's merely an intermediate component to pass things along.

• The components you pass to the RouteViewPortal are actually being rendered in a different place in the component tree.
• Keep this in mind when using things like react context and state (this is a limitation I'm currently trying to fix).

RouteViewPortal Component: Props

RouteViewPortal Example

• 📌 Declaration: RouteViewPortalExample01.tsx

// 📝 Note: for the sake of brevity, some of the code is omitted...
export function RouteViewPortalExample01(){
  const [index, setIndex] = React.useState(0);

  return (
    <SafeAreaView style={styles.routeContainer}>
      <RouteViewPortal
        routeOptions={{
          // Change the navigation bar title text
          routeTitle: `index: ${index}`,

          // Disable large tile
          largeTitleDisplayMode: 'never',

          // Set the status bar tint to 'white'
          statusBarStyle: 'lightContent',
          
          // Customize navigation bar appearance...
          navBarAppearanceOverride: {
            mode: 'appearance',
            useStandardAppearanceAsDefault: true,

            standardAppearance: {
              // Set the navigation bar tint to red
              backgroundColor: Colors.RED.A700,

              // Make the back button text white
              backButtonAppearance: {
                style: 'plain',
                normal: {
                  titleTextAttributes: {
                    color: 'white',
                    fontSize: 16,
                    fontWeight: '600',
                  },
                },
              },

              // Make the back button icon white
              backIndicatorImage: {
                type: 'IMAGE_SYSTEM',
                imageValue: {
                  systemName: 'chevron.left',
                  weight: 'semibold',
                },
                imageOptions: {
                  tint: 'white',
                  renderingMode: 'alwaysOriginal',
                },
              },
            }
          },
        }}

        // Use a custom component for navigation bar title
        renderNavBarTitleItem={({routeOptions}) => (
          <TouchableOpacity 
            style={styles.buttonContainer}
            onPress={() => {
              // Reset the index when pressed
              setIndex(0);
            }}
          >
            <Text style={styles.buttonLabel}>
              {routeOptions.routeTitle ?? 'N/A'}
            </Text>
          </TouchableOpacity>
        )}

        // Use a custom component for navigation bar right item
        renderNavBarRightItem={() => (
          <View style={styles.navBarLeftItemContainer}>
            <TouchableOpacity
              style={[styles.buttonContainer, styles.buttonRightSpace]}
              onPress={() => {
                // Decrement the index when pressed
                setIndex(prevIndex => (prevIndex - 1));
              }}
            >
              <Text style={styles.buttonLabel}>
                {`--`}
              </Text>
            </TouchableOpacity>
            <TouchableOpacity
            style={styles.buttonContainer}
            onPress={() => {
              // Increment the index when pressed
              setIndex(prevIndex => (prevIndex + 1));
            }}
          >
            <Text style={styles.buttonLabel}>
              {`++`}
            </Text>
          </TouchableOpacity>
          </View>
        )}
      />
      <View style={styles.rootContainer}>
        <Text style={styles.textTitle}>
          {`Current Index: ${index}`}
        </Text>
      </View>
    </SafeAreaView>
  );
};

D.1.3. RouteViewEvents Component

This component allows you to subscribe and listen to the route-related events for the current route (e.g. these events include things like: when a route is about to be pushed or popped, or when a navigation bar item has been pressed, etc).

Similar to the RouteViewPortal component:

• 1. this component doesn't actually render anything, and
• 2. this component is also required to be used inside a route.
  • This is because, like the RouteViewPortal component, this component also relies on react context to communicate to the parent NavigatorRouteView component and receive the route-related events.

Internally, every route has an associated event emitter (i.e. a NavigatorRouteViewEventEmitter instance).

• The "route event emitter" instance, as the name would suggest, emits route-related events. You can use the route event emitter to manually subscribe and listen for events.
• The route's event emitter can be accessed via the route's navigation object (e.g. NavigationObject.getRefToNavRouteEmitter).
• Internally, this component uses the route's event emitter object to subscribe and listen to the route events.
• 💡 Tip: As an alternative, there's also the useNavRouteEvents hook.

Here is a list a list of the event props that this component supports. The various route-related events are documented and explained in the NavigatorRouteViewEvents section.

• Push/Pop-related Events
  • onRouteWillPush
  • onRouteDidPush
  • onRouteWillPop
  • onRouteDidPop

• Focus/Blur-related Events
  • onRouteWillFocus
  • onRouteDidFocus
  • onRouteWillBlur
  • onRouteDidBlur

• Navigation Bar Item-related Events
  • onPressNavBarLeftItem
  • onPressNavBarRightItem

• Search Bar-Related Events
  • onUpdateSearchResults
  • onSearchBarCancelButtonClicked
  • onSearchBarSearchButtonClicked

RouteViewEvents Component Example

import { RouteViewEvents } from 'react-native-ios-navigator';

// Route to show in the navigator
function ExampleRoute(props){
  return (
    <SafeAreaView>
      <RouteViewEvents
        onRouteDidPush={({nativeEvent}) => {
          console.log(`Route ${nativeEvent.routeKey} was pushed...`);
        }}
      />
    </SafeAreaView>
  );
};

D.1.4. RouteHeaderView Component

A common UI navigation pattern is having a large header at the very top of the screen that acts as the centerpiece for a route.

• That header will either remain at a fixed size, or expand and collapse during scrolling.
• Check out NavigatorShowcase01, NavigatorShowcase02 and NavigatorShowcase03 for some examples.

The navigation bar cannot be easily customized (this is especially true you're trying to change the height).

• As such, this makes things like extending the navigation bar's height to show some custom UI elements underneath the title bar very difficult.
• It's also undesirable to create a custom built solution because the built-in navigation bar has a lot of expected native behaviors/functionality that will be hard to re-create (transitions, the back button, etc).
• To workaround this, some apps (e.g. spotify's album/playlist screen, etc) will just make the navigation bar's background transparent, and then show their custom UI elements underneath it.
  • Other apps (like twitter's profile screen) will simply just hide navigation bar entirely, and show their own custom view (you can also do that using this library by pushing a route with RouteOptions.navigationBarVisibility).

This component uses the "transparent navigation bar" approach. When in use, this component is displayed behind the navigation bar, and is anchored to the top of the screen.

• The header can either have a fixed height, or it can be paired with a scroll view so that the header will expand or collapse as the user scrolls.
• In order for your "custom navigation bar" to receive touch events, set RouteOptions.allowTouchEventsToPassThroughNavigationBar to true.

RouteHeaderView Component Props

D.2. Context

D.2.1. NavigationContext

TBA

D.2.2. NavigatorUIConstantsContext

TBA

D.3. Hooks

D.3.1. useNavRouteEvents

TBA

D.3.2. useNavigation

TBA

D.3.2. useNavigatorUIConstants

TBA

D.4. Objects and Types

This library is written using typescript. As such, all of the objects/types mentioned in the documentation (and all of the types exported by the library) will have a corresponding type declaration. Those type declaration can usually be found in the src/types directory. If a particular object is not documented here, please refer to those type declaration files instead.

📄 Object Class: TSEventEmitter

See @dominicstop/ts-event-emitter for documentation.

📄 NavigatorRouteViewEventEmitter.ts

• 📌 Declaration: NavigatorRouteViewEventEmitter,ts

Type: NavigatorRouteViewEventEmitter

This type represents a route's event emitter that is used to broadcast and listen to route-related events (e.g. route lifecycle, navigation bar-related events, etc). The route event emitter is a TSEventEmitter object instance that is pre-typed with an event map based on the NavigatorRouteViewEvents enum.

Enum: `NavigatorRouteViewEvents

NavigatorRouteViewEvents Push/Pop-related Events

These events are triggered when the current route is about to be pushed or popped from the navigation stack.

NavigatorRouteViewEvents Focus/Blur-related Events

These events are triggered whenever the current route will receive or lose focus (this usually occurs whenever a route is pushed and popped from the navigation stack).

NavigatorRouteViewEvents Navigation Bar Item-related Events

📝 Note: When using a custom navigation bar items (e.g. renderNavBarLeftItem, etc.), the onPressNavBar events will not be triggered.

• Instead, use a button component (e.g. TouchableOpacity), and then wrap your custom navigation bar item inside it.

💡 Tip: It's possible to have more than one navigation bar item.

• As such, to differentiate which item is pressed, you can use the properties provided by event.nativeEvent object that you'll receive from the OnPressNavBarItemEvent.
• Some of those properties are nativeEvent.key (an optional user-defined string), and nativeEvent.index (the item's placement in the group).
  

NavigatorRouteViewEvents Search Bar-Related Events

These events are related to the route's search bar. A route can be configured to have a UISearchBar in the navigation bar via the RouteOptions.searchBarConfig property.

📄 NavRouteConfigItem.ts

• 📌 Declaration: NavRouteConfigItem.ts

Object Type: NavRouteConfigItem

This type is a union of NavRouteConfigItemJS and NavRouteConfigItemNative (i.e. so you can assign either a NavRouteConfigItemJS object or a NavRouteConfigItemNative object).

This type is used to configure a route item. For "JS/React" routes, use NavRouteConfigItemJS, and for native routes use NavRouteConfigItemNative.

Object Type: NavRouteConfigItemJS

This type is used to create and configure a "JS/React" route.

Object Type: NavRouteConfigItemNative

This type is used to create and configure a "native" route.

📄 RouteOptions.ts

• 📌 Declaration: RouteOptions.ts

Object Type: RouteOptions

The properties that are related to each other are grouped together into their own sections.

RouteOptions: General Properties

RouteOptions: Transition Config-Related Properties

RouteOptions: Navigation Bar Config-Related Properties

RouteOptions: Navigation Bar Item Config-Related Properties

RouteOptions: Navigation Bar Back Item Config-Related Properties

RouteOptions: Override-related Properties

📄 NavigationObject.ts

• 📌 Declaration: NavigationObject.ts

Object Type: NavigationObject

TBA

NavigationObject: General Properties

NavigationObject: Navigation Commands

See "NavigatorView Navigation Commands" section for more info.

NavigationObject: Convenience Navigation Commands

See "NavigatorView Convenience Navigation Commands" section for more info.

NavigationObject: General/Misc. Navigation Commands

See "NavigatorView General/Misc. Methods" section for more info.

NavigationObject: Route Commands

NavigationObject: "Get Ref" Commands

📄 NavRouteItem.ts

• 📌 Declaration: NavRouteItem.ts

Object Type: NavRouteItem

TBA

Object Type: NavRouteStackItem

Represents an active route item in the navigation stack. This type extends NavRouteItem, as such they share the same properties.

Object Type: NavRouteStackPartialItem

Used in the NavigatorView.SetRoutesTransformCallback function. Represents either an active route in the navigation stack, or a route that is about to be created and added to the navigation stack.

📄 NavBarAppearanceConfig.ts

• 📌 Declaration: NavBarAppearanceConfig.ts

Object Type: NavBarAppearanceCombinedConfig

The NavBarAppearanceCombinedConfig tagged/discriminated union object type is used to customize the appearance of the navigation bar. This object is a union of two objects, namely: NavBarAppearanceConfig, and NavBarAppearanceLegacyConfig and it's separated via the shared mode property. The former can be used if the mode property is set to appearance, and the latter can be used if mode is set to legacy.

The navigation bar can be customized either via the "legacy" mode (i.e. using the legacy customizations-related API), or via the "appearance" mode (i.e. using the iOS 13+ UINavigationBarAppearance API).

📝 Note The legacy mode only exists for backwards compatibility (e.g. for iOS versions that are below iOS 13). As such if you're not planning on supporting iOS 12 and below, you should probably use appearance mode instead.

• There are some things that legacy mode can do that appearance mode can't (and vice versa). For example, via legacy mode, you can set the global tint of all the navigation bar elements via tintColor.

Example Snippet

const navBarAppearanceLegacy = {
	mode: 'appearance',
	// `NavBarAppearanceConfig`-related properties
  // ...
};

const navBarAppearance = {
  mode: 'legacy',
  // `NavBarAppearanceLegacyConfig`-related properties
  // ...
};

Object Type: NavBarAppearanceLegacyConfig

Object Type: NavBarAppearanceConfig

Object type that lets you customize the navigation bar using the iOS 13+ "appearance" API.

Object Type: NavBarAppearance

TBA

Enum: BarButtonItemAppearance

• 📌 Declaration: BarButtonItemAppearance

TBA

📄 NavBarItemConfig.ts

• 📌 Declaration: NavBarItemConfig.ts

Object Type: NavBarItemConfigBase

This type is an object tagged union type, with the type property being the tag that separates the unions. The table below defines the possible valid values that can be assigned to the type property.

Object Type: NavBarItemConfigShared

TBA

Object Type: NavBarItemConfigCustom

TBA

Object Type: NavBarItemBackgroundImageConfig

TBA

Object Type: NavBarItemConfig

An intersection type that supports a combination of properties from NavBarItemConfigBase and NavBarItemConfigShared, i.e. equivalent to NavBarItemConfigBase & NavBarItemConfigShared in typescript.

Object Type: NavBarBackItemConfig

An intersection type that supports a combination of properties from NavBarItemConfigBase and NavBarItemConfigShared, i.e. equivalent to NavBarItemConfigBase & NavBarItemConfigShared in typescript.

Object Type: NavBarItemsConfig

A union type that can either be an array of NavBarItemConfig or a tuple containing a single element of NavBarItemConfigCustomBase.

📄 RouteHeaderConfig.ts

• 📌 Declaration: RouteHeaderConfig.ts

Object Type: RouteHeaderConfig

This type is an object tagged union type, with the headerMode property being the tag that separates the unions. The table below defines the possible valid values that can be assigned to the headerMode property.

Object Type: HeaderHeightConfig

TBA

Union String Type: HeaderHeightPreset

TBA

HeaderHeightConfig

📄 RouteSearchControllerConfig

• 📌 Declaration: RouteSearchControllerConfig

Object Type: RouteSearchControllerConfig

TBA

Union String Type: NativeRouteData

TBA

Object Interface: RouteContentProps

• 📌 Declaration: NavigatorRouteView

TBA

Object Type: RouteConstantsObject

• 📌 Declaration: RNINavigatorRouteViewModule

TBA

Object Type: NavigatorConstantsObject

• 📌 Declaration: RNINavigatorViewModule

Object Type: NativeRouteData

This type is an object tagged union type, with the type property being the tag that separates the unions. The table below defines the possible valid values that can be assigned to the type property.

Object Type: NavigatorConstantsObject

TBA

📄 ImageItemConfig.ts

• 📌 Declaration: ImageItemConfig.ts

Object Type: ImageItemConfig

This type is an object tagged union type, with the type property being the tag that separates the unions. The table below defines the possible valid values that can be assigned to the type property.

Object Type: ImageResolvedAssetSource

TBA

Object Type: ImageRectConfig

TBA

Object Type: ImageGradientConfig

TBA

Object Type: ImageSystemConfig

TBA

Enum: NavigatorErrorCodes

• 📌 Declaration: NavigatorError

TBA

Object Constant: NavBarAppearancePresets

• 📌 Declaration: NavBarAppearancePresets

TBA

Undocumented Types

TBA

D.6. Native-Related

Native/Swift Integration

RNINavigatorManager

RNINavigatorNativeCommands

RNINavigatorManagerDelegate

RNINavigatorRouteBaseViewController

RNINavigationControllerConfig

D.7. Articles + Discussions

Discussion: RouteOptions Precedence

There are multiple ways to set a route's routeOptions config, but only one of them will take effect (in other words, a route's routeOptions can be overridden when all of the route options are being merged together). The table below will list the order of precedence in which the routeOptions gets applied (ordered by increasing priority).

E. Getting Started Guide

A01 - Navigation Hello World

Here's a bare minimum example: a navigator with a single route.

🔗 Full Example

import * as React from 'react';
import { SafeAreaView, TouchableOpacity, Text, StyleSheet } from 'react-native';

import { NavigatorView, RouteContentProps } from 'react-native-ios-navigator';

// Route - 'routeA'
// This is the component that gets shown when 'routeA' is pushed. 
function ExampleRoute(props){
  return (
    <SafeAreaView style={styles.routeContainer}>
      <TouchableOpacity
        style={styles.button}
        onPress={() => {
          // when this button is pressed, push a route 
          // with the "route key" value of 'routeA'.
          props.navigation.push({
            routeKey: 'routeA'
          });
        }}
      >
        <Text style={styles.buttonText}> 
          Push: 'RouteA' 
        </Text>
      </TouchableOpacity>
    </SafeAreaView>
  );
};

export function ExampleA01(){
  return (
     <NavigatorView
      // The object that's passed to the `NavigatorView.routes` 
      // prop defines what routes can be used in the navigator.
      //
      // Note: The object that is passed to this prop is referred to as
      // the "route map" (e.g. `NavRoutesConfigMap`).
      routes={{
        // The key of the property is used as the "route key" of the route.
        // E.g. so this is a route that has the `routeKey` value of 'routeA'.
        //
        // Note: The object that's assigned to the `routeKey` is referred to
        // as the "route config" (e.g. `NavRouteConfigItem`).
        routeA: {
          // Now we need to provide a config... we want to show the 
          // `ExampleRoute` component when this route is "pushed".
          //
          // The `renderRoute` property accepts a function that returns a
          // component to show in the route.
          renderRoute: () => (
            <ExampleRoute/>
          ),
        }
      }}
      // This prop controls the initial routes to show when the navigator
      // first mounts.
      initialRoutes={[{routeKey: 'routeA'}]}
    />
  );
};

A02 - Routes and Route Config

The "route config", as the name would suggest, is used to configure a route. As such, each route has a corresponding "route config" object.

The route config object's renderRoute property (e.g.NavRouteConfigItem.renderRoute ) defines what route to show when it gets pushed.

The route config object can also be customized and configured further via the defaultRouteOptions property (e.g. e.g.NavRouteConfigItem.defaultRouteOptions).

🔗 Full Example

// 📝 Note: for the sake of brevity, some of the code is omitted...
export function ExampleA02(){
  return (
     <NavigatorView
      // ...
      routes={{
        routeA: {
          // The route can be configured/customized further via the
          // `NavRouteConfigItem.defaultRouteOptions` property.
          routeOptionsDefault: {
            routeTitle: 'Hello World',
            prompt: 'Lorum Ipsum',

            // disable the "large title" for this route
            largeTitleDisplayMode: 'never',

            // show a button on the right side of the
            // navigation bar
            navBarButtonRightItemsConfig: [{
              type: 'TEXT',
              title: 'ABC',
              tintColor: 'red',
            }]
          },
          renderRoute: () => (
            <ExampleRoute/>
          ),
        }
      }}
    />
  );
};

A03 - Initial Routes

As mentioned before, the NavigatorView.initialRoutes prop controls what routes to show when the navigator first mounts.

For most cases, you only want one initial route. But you can define multiple initial routes if you want to (e.g. for the purpose of state restoration, etc).

🔗 Full Example

// 📝 Note: for the sake of brevity, some of the code is omitted...
export function ExampleA03(){
  return (
     <NavigatorView
      // ...
      //
      // show multiple initial routes...
      // Note: this prop accepts an array of `NavRouteItem` objects
      initialRoutes={[{
        routeKey: 'routeA',
        routeOptions: {
          routeTitle: '01 (Root)'
        }
      }, {
        routeKey: 'routeA',
        routeOptions: {
          routeTitle: '02'
        }
      }, {
        routeKey: 'routeA',
        routeOptions: {
          routeTitle: '03'
        }
      }, {
        routeKey: 'routeA',
        routeOptions: {
          routeTitle: '04'
        }
      }, {
        routeKey: 'routeA',
        routeOptions: {
          routeTitle: '05'
        }
      }, {
        routeKey: 'routeA',
        routeOptions: {
          routeTitle: '06'
        }
      }]}
    />
  );
};

Navigation Commands Basics

B01 – The NavigationObject

The "navigation object" contains information about the current route, and is also used to send commands to the navigator (e.g. pushing and popping routes, etc).

There are two ways to get the navigation object. The first way is to simply get the navigation object via the props:

// 1. your route component will automatically receive the `NavigationObject` via props.
function ExampleRoute(props){
  const { navigation } = props;
  return (
    // ...
  );
};

// 2. If you are using typescript, you can use (or extend) the `RouteContentProps` type.
import type { RouteContentProps } from 'react-native-ios-navigator';

function ExampleRoute(props: RouteContentProps){
  const text = `The current route key is: ${props.navigation.routeKey}`;
  return (
    // ...
  );
};

The second way to get the navigation object is via context:

// 1. For convenience, there's a pre-built hook to get the navigation object
// via context.
import { useNavigation } from 'react-native-ios-navigator';

function ExampleRoute(){
  const navigation = useNavigation();
  return (
    // ...
  );
};

// 2. Or altenatively, you can use the `NavigationContext` directly for more
// flexibility and control.
import { NavigationContext } from 'react-native-ios-navigator';

function ExampleRoute(){
  return (
    <NavigationContext.Consumer>
      {(navigation) => (
        // ...
  		)}
    </NavigationContext.Consumer>
  );
};
  

B02 – Pushing Routes

Via the navigation object, you can send commands to the navigator. For example, you can push a route into the navigation stack using the "push" command:

// The push command accepts an object...
navigation.push({
  // The "route key" of the route that is to be shown
  routeKey: 'routeA'
});

B03 - Forwarding Data To Routes

Using the push navigation command, you can send data (i.e. "route props") to the next route. The data can then be read via the navigation object (i.e. NavigationObject.routeProps).

🔗 Full Example

// 📝 Note: for the sake of brevity, some of the code is omitted...
function ExampleRoute(props){
  // Get the count from the prev. route.
  const prevCount = props.navigation.routeProps?.count ?? 0;

  // Save the count to state
  const [count] = React.useState(prevCount);

  return (
    <SafeAreaView style={styles.routeContainer}>
      <TouchableOpacity
        style={styles.button}
        onPress={() => {
          // Push route when this button is pressed...
          props.navigation.push({
            routeKey: 'routeA',
            routeProps: {
              // ... and send the count to the next route.
              count: count + 1,
            },
            routeOptions: {
              routeTitle: `Count: ${count}`
            },
          });
        }}
      >
        <Text style={styles.buttonText}> 
          {`Push and Increment Counter`}
        </Text>
      </TouchableOpacity>
    </SafeAreaView>
  );
};

B04 - Configure The Next Routes

The "route options" of a route can also be set via a navigation command. The "route options" provided by the navigation command will be combined with the route's pre-existing route options (i.e. the route options that were provided via the route config: NavRouteConfigItem.defaultRouteOptions).

🔗 Full Example

// 📝 Note: for the sake of brevity, some of the code is omitted...
function ExampleRoute(props){
  return (
    <SafeAreaView style={styles.routeContainer}>
      <TouchableOpacity
        style={styles.button}
        onPress={() => {
          // Push route when this button is pressed...
          props.navigation.push({
            routeKey: 'routeA',
            // ...and set the route's route options
            routeOptions: {
              largeTitleDisplayMode: 'never',
              routeTitle: 'Hello World',
              prompt: 'Lorum Ipsum',
            },
          });
        }}
      >
        <Text style={styles.buttonText}> 
          Push: 'RouteA' + Send Route Options 
        </Text>
      </TouchableOpacity>
    </SafeAreaView>
  );
};

B05 - Popping Routes

To programmatically pop the current route, you can use the pop navigation command.

🔗 Full Example

// 📝 Note: for the sake of brevity, some of the code is omitted...
function ExampleRoute(props){
  return (
    <SafeAreaView style={styles.routeContainer}>
      {/** ... */}
      <TouchableOpacity
        style={styles.button}
        onPress={() => {
          // Pop current route when the button is pressed
          props.navigation.pop();
        }}
      >
        <Text style={styles.buttonText}> 
          Pop Current Route
        </Text>
      </TouchableOpacity>
    </SafeAreaView>
  );
};

B06 - Extra Options

Most of the navigation commands can accept extra options. The extra options can be used to enable/disable the transition animation, or provide a custom transition config to use, etc.

🔗 Full Example

// 📝 Note: for the sake of brevity, some of the code is omitted...
function ExampleRoute(props){
  return (
    <SafeAreaView style={styles.routeContainer}>
      <TouchableOpacity
        style={styles.button}
        onPress={() => {
          // Push 'routeA' with a custom transition
          props.navigation.push({
            routeKey: 'routeA',
          }, {
            transitionConfig: {
              type: 'GlideUp',
              duration: 0.75
            }
          });
        }}
      >
        <Text style={styles.buttonText}> 
          Push: 'RouteA'
        </Text>
      </TouchableOpacity>
      <TouchableOpacity
        style={styles.button}
        onPress={() => {
          // Pop current route w/ a custom transition
          props.navigation.pop({
            transitionConfig: {
              type: 'FlipHorizontal',
              duration: 0.75,
            }
          });
        }}
      >
        <Text style={styles.buttonText}> 
          Pop Current Route
        </Text>
      </TouchableOpacity>
    </SafeAreaView>
  );
};

Customizations Basics

C01 - Navigator Customization

You can "globally" apply customization on the navigation bar via setting some props on the navigator itself. Navigator-level customizations are "global" in the sense that it'll be applied to all the routes that will be shown in the navigator.

🔗 Full Example

// 📝 Note: for the sake of brevity, some of the code is omitted...
export function ExampleC01(){
  return (
     <NavigatorView
      // ...
      // Customize the look of the navigation bar
      navBarAppearance={{
        // Use the appearance API (i.e. iOS 13 and above) to style
        // the navigation bar
        mode: 'appearance',
        useStandardAppearanceAsDefault: true,

        standardAppearance: {
          // Set nav bar bg to red
          backgroundColor: 'red',
          
          // Make the nav bar title white
          titleTextAttributes: {
            color: 'white',
            fontSize: 16,
            fontWeight: 'bold',
          },

          // Add a gradient shadow below the nav bar
          shadowImage: {
            type: 'IMAGE_GRADIENT',
            imageValue: {
              colors: ['rgba(255,0,0,1)', 'rgba(255,0,0,0)'],
              type: 'axial',
              height: 75,
              startPoint: 'top',
              endPoint: 'bottom',
            },
          },
        },
      }}
    />
  );
};

Per-Route Customization

Dynamic Customizations

Navigation Bar Items (Basic)

F. Usage and Examples

F.1. Navigation Bar Customizations

Navigation Bar: Appearance/Legacy API

Navigation Bar — Legacy Customizations

Navigation Bar — Appearance Customizations

Navigation Bar: Custom Bar Items

Navigation Bar: Search Bar

Navigation Bar: RouteHeaderView

F.2. Navigation Commands

Navigation Command List

Navigation Command: push

Navigation Command: pop

Navigation Command: popToRoot

Navigation Command: removeRoute

Navigation Command: removeRoutes

Navigation Command: replaceRoute

Navigation Command: insertRoute

Navigation Command: replaceRoute

Navigation Command: setRoutes

F.3. Navigation Events

NavigatorView Events

Route-Level Events

Route Events: NavigatorRouteViewEventEmitter

Route Events: RouteViewEvents Component

Route Events: useNavRouteEvents Hooks

Route Lifecycle Events

Navigation Bar-Related Events

F.4. Native Integration

Creating Native Routes

Route Customizations

Pushing Routes From Native-Side

Using Native Routes From React-Side

Getting The RNINavigatorView Instance