Skip to content

dominicstop/react-native-ios-navigator

Repository files navigation

react-native-ios-navigator

A native wrapper component around UINavigationController for react-native.

gif-showcase-00

🚧⚠️ 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).


Section + Link Description
⭐️ Getting Started Guide Discussion + step by step guide (w/ accompanying gifs + screenshots) on how to use this library and its various components.

Related Links:
1️⃣ Installation
2️⃣ Basic Usage
πŸ’– Usage and Examples Example usage that covers the various components and functionality of this library.
πŸ’« Showcase, Tests, and Demos Just some gifs, screenshots + vibes that shows what this library can do.
πŸ“ Documentation Documentation for all the various components, functions, types, etc.

Sub-Section Links:
1️⃣NavigatorView Component
2️⃣RouteViewPortal Component
3️⃣RouteViewEvents Component
4️⃣RouteHeaderView Component
5️⃣ Context
6️⃣ Hooks
7️⃣ Objects and Types
8️⃣ Native-Related



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


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.

installation-additional-setup-01


Troubleshooting

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

installation-troubleshooting-00


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:

installation-troubleshooting-01


Versions

Library Version Compatibility
0.4.0+ iOS 10 to iOS 15
Xcode 13
0.3.1 and Below iOS 10 to iOS 14
Xcode 12



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/>
          ),
        }
      }}
    />
  );
};

GettingStartedGuide-ExampleA01


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
Prop Name and Type Description
πŸ”€ Required: routes

βš›οΈ NavRoutesConfigMap
Configures what routes can be used inside the navigator.

This prop accepts a NavRoutesConfigMap object. This object is a map/dictionary of NavRouteConfigItem objects, where in the key of each property is its routeKey (e.g. { RouteA: {...}, RouteB: {...} }).

These objects are used to create and configure the routes. Those "route config" objects include things like:
β€’ A. what component to show when the route becomes active (i.e. the NavRouteConfigItem.renderRoute property),
β€’ B. the initial routeProps that the route will receive (e.g. NavRouteConfigItem.initialRouteProps), and
β€’ C. other misc. options that'll determine the look of the navigation bar, the route's transitions, etc. (i.e. NavRouteConfigItem.routeOptionsDefault).

πŸ“ Note: The routeKey for the route config object must be unique for each route item.

There are actually two types of routes that you can use:
β€’ A. The first one is a "JS route" (i.e. a route defined in react/js-side using standard react components).
β€’ B. The second one is a "native route" (i.e. a route defined in the native-side using native code (e.g. UIViewController + storyboards, auto layout, etc).

πŸ“Œ Related Sections:
β€’ RouteOptions
β€’ RouteOptions Precedence
β€’ NavRouteConfigItem
πŸ”€ Required: initialRoutes

βš›οΈ Array<NavRouteItem>
Used by the navigator to determine which initial routes to show when the navigator first mounts.

This prop accepts an array of NavRouteItem objects. The routeKey values in the objects must match with a route configured in the routes prop.

This prop basically represents the navigation stack during the first mount (e.g. with the first item being the root route, and the last item being the topmost active route).

For example, if you pass [[{routeKey: 'A'}, {routeKey: 'B'}]] as the initial routes, then route "A" will become the root route, and route "B" will become the topmost route. Thus, on the first mount route "B" will first be shown, and by pressing the back button, route "B" will be popped, and then route "A" will be shown.

πŸ’‘ Tip: This behavior of being able to set the initial routes is useful for state-restoration (or for when you want to show a different initial route based on some condition).
βš›οΈ ViewProps This component also supports all the standard props from a <View/> component.
πŸ”€ style

βš›οΈ ViewStyle
The style applied to the the NavigatorView component itself.

πŸ“ Note: The layout size of the NavigatorView will also determine the layout size of the routes, so if the size of the navigator is 100 x 100, then the routes will also be 100 x 100.
πŸ”€ navBarPrefersLargeTitles

βš›οΈ boolean

✳️ Default: true on iOS 11+
Specifies whether or not to use the large title style for the navigation bar title. Defaults to true on iOS 11 and above.

Maps to the UINavigationBar.prefersLargeTitle property,

πŸ“ Note: This prop can be overridden on a per route basis either via largeTitleDisplayMode in the NavigatorView.routes prop, or via the RouteViewPortal.routeOptions prop.
πŸ”€ navBarAppearance

βš›οΈ NavBarAppearanceCombinedConfig
This prop allows for the customization of the UINavigationBar. The navigation bar can be customized via two modes, namely:
β€’ A. "legacy" mode (iOS 12 and below), and
β€’ B. "appearance" mode (iOS 13 and above).

The "legacy" mode, as the name would suggest, uses "legacy customizations" (where in the navigation bar is customized using the old API via directly manipulating the navigation bar object's properties).

The "appearance" mode on the other hand, uses UINavigationBarAppearance to apply customizations for each of the "navigation bar" styles/states, namely:
1️⃣ standardAppearance (normal height),
2️⃣ compactAppearance (compact-height, e.g. iPhones in landscape, etc.),
3️⃣ scrollEdgeAppearance (when the navigation bar doesn't have content behind it and is currently scrolled all the way to the top), and
4️⃣ compactScrollEdgeAppearance (a combination of compact and scroll edge, requires iOS 15+) .

πŸ“ Note: There is one big caveat though, once "appearance" mode is used, "legacy" mode no longer works (it's some sort of bug in UIKit). In other words, switching between the two modes is not supported, only stick to one. When targeting iOS 12 and below, use "legacy", otherwise use "appearance".

πŸ’‘ Tip: Check the guides section for examples on how to customize the navigation bar, or browse the NavBarAppearanceCombinedConfig object for the full list of properties.

πŸ’‘ Tip: The navigation bar can also be customized on a per-route basis via the RouteOptions.navBarAppearanceOverride. You can set this property either via routeOptionsDefault in a route's config (in the NavigatorView.routes prop), or via the RouteViewPortal component using the RouteViewPortal.routeOptions prop.
πŸ”€ isNavBarTranslucent

βš›οΈ boolean
Determines whether or not the the navigation bar is translucent. Maps to UINavigationBar.isTranslucent.
isInteractivePopGestureEnabled

βš›οΈ boolean
Enables or disables the interactivePopGestureRecognizer. In other words, this prop sets whether swiping on the left edge of the screen will pop the current route. Defaults to true.
πŸ”€ shouldSwizzleRootViewController

βš›οΈ boolean
Determines whether or not the root view controller's default implementation is changed at run-time (i.e. "swizzled") to enable certain features (e.g. like enabling "view controller based status bar" via delegating childForStatusBarStyle to a child view controller, etc).

The "injected" implementation is lifted from RNIRootViewController.

Defaults to true, however this will only take effect for the first NavigatorView component, and also only if the parent view controller is the same instance as the one in window.rootViewController.

For brownfield projects with native code (or for projects with an existing navigation solution), set this to false to disable this behavior.
πŸ”€ disableTransparentNavBarScrollEdgeAppearance

βš›οΈ boolean

✳️ Default: true
In iOS 15+ the navigation bar by default is now configured to have a transparent background until the user scrolls and there's some content behind the navigation bar (i.e. the scrollEdgeAppearance is now configured to be transparent by default).

This prop determines whether or not to apply a background to navigation bar using scrollEdgeAppearance . Set this to false if you want to keep the default behavior

πŸ“ Note A: You can manually do what this prop does by providing your own scrollEdgeAppearance appearance config either globally via the NavigatorView.navBarAppearance prop, or on a per-route basis via the RouteOptions.navBarAppearanceOverride property.

πŸ“ Note B: This prop only takes effect on iOS 15+ and when a route disables the large title. This prop does not affect native routes.

NavigatorView Render Props
Prop Name and Type Description
πŸ”€ renderNavBarLeftItem

βš›οΈ RenderNavItem i.e. (navigation: NavigationObject) => ReactElement Β¦ null Β¦ undefined

πŸ“Œ navigation: NavigationObject
Sets a default left item for the navigation bar for all the routes.

πŸ“ Note A: The left navigation bar item can be overridden/replaced on a per route basis via NavRouteConfigItem.renderNavBarLeftItem in the NavigatorView.routes prop, or via RouteViewPortal.renderNavBarLeftItem prop.

πŸ“ Note B: If this prop is used, it'll implicitly set RouteOptions.navBarButtonLeftItemsConfig to { type: 'CUSTOM' } for a route's routeOptions. So if the navBarButtonLeftItemsConfig is explicitly set to anything other than "custom", then this prop will not do anything.

πŸ“ Note C: If a route's RouteOptions.leftItemsSupplementBackButton is set to false (which it isn't by default), then it will replace the back button (i.e. the back button will not be shown).
πŸ”€ renderNavBarRightItem

βš›οΈ RenderNavItem i.e. (navigation: NavigationObject) => ReactElement Β¦ null Β¦ undefined

πŸ“Œ navigation: NavigationObject
Sets a default right item for the navigation bar for all the routes.

πŸ“ Note A: The right navigation bar item can be overridden/replaced on a per route basis via NavRouteConfigItem.renderNavBarRightItem in the NavigatorView.routes prop, or via RouteViewPortal.renderNavBarRightItem prop.

πŸ“ Note B: If this prop is used, it'll implicitly set RouteOptions.navBarButtonRightItemsConfig to { type: 'CUSTOM' } for a route's routeOptions. So if the navBarButtonRightItemsConfig is explicitly set to anything other than "custom", then this prop will not do anything.
πŸ”€ renderNavBarTitleItem

βš›οΈ RenderNavItem i.e. (navigation: NavigationObject) => ReactElement Β¦ null Β¦ undefined

πŸ“Œ navigation: NavigationObject
Sets a default title item for the navigation bar for all the routes.

πŸ“ Note: The title navigation bar item can be overridden/replaced on a per route basis via NavRouteConfigItem.renderNavBarTitleItem in the NavigatorView.routes prop, or via RouteViewPortal.renderNavBarTitleItem prop.

πŸ’‘ Tip: You can access the route's routeTitle via the navigation object (i.e. navigation.routeOptions.routeTitle).

NavigatorView Event Props
Prop Name and Type Description
πŸ”€ onNavRouteWillPop

βš›οΈ OnNavRoutePopEvent

πŸ“Œ OnNavRoutePopEventObject
Event that is triggered when a route is about to be "popped" from the navigation stack (i.e. when the pop transition has started).
πŸ”€ onNavRouteDidPop

βš›οΈ OnNavRoutePopEvent

πŸ“Œ OnNavRoutePopEventObject
Event that is triggered when a route has been "popped" from the navigation stack (i.e. the pop transition has already been completed).
πŸ”€ onCustomCommandFromNative

βš›οΈ OnCustomCommandFromNativeEvent

πŸ“Œ OnCustomCommandFromNativeEventObject
Event that is triggered from the native-side via the RNINavigatorNativeCommands.sendCustomCommandToJS delegate method.

This event exists to receive custom user-defined commands from a RNINavigatorView (i.e. for custom native code integration).
πŸ”€ onNavRouteWillShow

βš›οΈ OnNavRouteWillShowEvent

πŸ“Œ OnNavRouteWillShowEventObject
Gets called just before the navigator shows the route (similar to onRouteWillFocus event).

This event maps to UINavigationControllerDelegate.navigationController(_:willShow:animated:).
πŸ”€ onNavRouteDidShow

βš›οΈ OnNavRouteDidShowEvent

πŸ“Œ OnNavRouteDidShowEventObject
Gets called after the navigator shows the route (similar to onRouteDidFocus event).

This event maps to UINavigationControllerDelegate.navigationController(_:didShow:animated:).
πŸ”€ onUIConstantsDidChange

βš›οΈ OnUIConstantsDidChangeEvent

πŸ“Œ OnUIConstantsDidChangeEventObject
Gets called whenever the UI-related constants changes (e.g. this event is triggered when the screen rotates, the navigation bar visibility is changed, etc).

The event object contains the current safe area values, status bar height, and the navigator frame.

πŸ’‘ Tip: You can also access the UI constants via NavigatorUIConstantsContext or via the useNavigatorUIConstants hook.

NavigatorView Component: Properties/Methods
NavigatorView General/Misc. Methods
Name Description
πŸ”€ getActiveRoutes

βš›οΈ () => Array<NavRouteStackItem>
Returns an array of NavRouteStackItem objects that represents the current state of the navigation stack.

This method is useful for getting the routeIndex of a particular route, or for getting the current active routes.
πŸ”€ sendCustomCommandToNative

βš›οΈ (commandKey: string, commandData: object Β¦ null) => Promise<object Β¦ null>
Will trigger the RNINavigatorViewDelegate.didReceiveCustomCommandFromJS delegate method for the current navigator view instance.

This method exists to send custom user-defined commands to the RNINavigatorView's delegate (i.e. for custom native code integration).

πŸ“Œ Check the native integration guide section for more details.
πŸ”€ getNavigatorConstants

βš›οΈ () => Promise<NavigatorConstantsObject>
Resolves to an object containing values related to UI (e.g. navBarHeight, navigator bounds, safeAreaInsets, statusBarHeight), and the current state of the navigator (e.g. whether a view controller is being presented modally, the current activeRoutes, the current topmost view controller, and the current visible view controller).
πŸ”€ dismissModal

βš›οΈ (animated: Bool) => Promise<void>
This will close any modals that are currently being presented.
πŸ”€ getMatchingRouteStackItem

βš›οΈ (routeDetails: NavRouteStackItemPartialMetadata) => NavRouteStackItem Β¦ undefined

πŸ“Œ routeDetails: NavRouteStackItemPartialMetadata

πŸ“Œ NavRouteStackItem
TBA
πŸ”€ getNavigationObjectForRoute

βš›οΈ (routeDetails: NavRouteStackItemPartialMetadata) => NavigationObject Β¦ undefined

πŸ“Œ routeDetails: NavRouteStackItemPartialMetadata

πŸ“Œ NavigationObject
TBA

πŸ“ Note: Internally, this command uses getMatchingRouteStackItem command to find the route that matches all of the criteria specified in the routeDetails argument.

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).

Name and Type Description
πŸ”€ push

βš›οΈ (routeItem, options?) => Promise<void>

πŸ“Œ routeItem: NavRouteItem
πŸ“Œ options: NavCommandPushOptions
Push a new route into the navigation stack. The routeItem to be pushed must be a route that is declared in the NavigatorView.routes prop. This command maps to the UINavigationController.pushViewController method.

The routeItem parameter accepts a NavRouteItem object. Via this object you can define what route to show using the NavRouteItem. routeKey property. You can also pass data to the new route using the NavRouteItem.routeProps property, or optionally pass new route options via the NavRouteItem.routeOptions property.

πŸ’‘ Tip: You can set a temporary push transition (e.g. FadePush, SlideLeftPush, etc), or disable the transition animation entirely via the options parameter.
πŸ”€ pop

βš›οΈ (options?) => Promise<void>

πŸ“Œ options: NavCommandPopOptions
Pop the current active route out of the navigation stack. This command maps to the UINavigationController.popViewController method.

πŸ’‘ Tip: You can set a temporary pop transition (e.g. FadePop, SlideLeftPop, etc.), or disable the transition animations entirely via the options parameter.
πŸ”€ popToRoot

βš›οΈ (options?) => Promise<void>

πŸ“Œ popToRoot: NavCommandPopOptions
Pop all the routes except the first route in the navigation stack. This can be used as a quick way to go back to the root route.

This command maps to the UINavigationController.popToRootViewController method.
πŸ”€ removeRoute

βš›οΈ (routeIndex: number, animated?: boolean = false) => Promise<void>
Removes a specific route from the navigation stack. The argument passed to routeIndex determines which route to remove from the navigation stack (e.g. a value of 0 means to move the root route, and so on).

β€’ πŸ’‘ Tip: You can call getActiveRoutes to get the current state of the navigation stack.

β€’ πŸ’‘ Tip: This command is useful for situations where in a given route in the navigation stack becomes "stale", i.e. it no longer makes sense to show that route when navigating backwards.

β€’ An example could be a user navigating from a "registration" route, to a "registration success" route. If the back button is pressed, it doesn't make sense for the "registration" route to appear again, so you remove it from the navigation stack.
πŸ”€ removeRoutes

βš›οΈ (routeIndices: number, animated?: boolean = false) => Promise<void>
Removes the specified routes from the navigation stack. The argument passed to routeIndices determines which routes to remove from the navigation stack, where a value of 0 means to remove the root route, and so on.

This command is similar to removeRoute, but this lets you remove multiple routes at once.

πŸ’‘ Tip: You can call getActiveRoutes to get the current state of the navigation stack.

πŸ’‘ Tip: Similar to removeRoute, this command is useful for selectively removing routes that have gone "stale" all at once.
πŸ”€ replaceRoute

βš›οΈ (prevRouteIndex: number, routeItem: NavRouteItem, animated?: boolean = false) => Promise<void>

πŸ“Œ routeItem: NavRouteItem
Replaces an existing active route in the navigation stack with a new route that matches the specified prevRouteIndex argument.

A new route will be created based on the specified routeItem provided, and it will then be used as the replacement route.

πŸ“ Note: Just like the push command, the routeItem must be a route that is declared in the NavigatorView.routes prop.

πŸ’‘ Tip: You can call getActiveRoutes to get the current state of the navigation stack.
πŸ”€ insertRoute

βš›οΈ (routeItem: NavRouteItem, atIndex: number, animated?: boolean = false) => Promise<void>

πŸ“Œ routeItem: NavRouteItem
Similar to the push command, this lets you create a new route based on the provided routeItem, and then add it to the navigation stack. But instead of only being able to add routes to the top, this command let's you arbitrarily add a route anywhere in the navigation stack based on the provided atIndex argument.

πŸ“ Note: The routeItem to be added must be a route that is declared in the NavigatorView.routes prop, and the atIndex argument must not exceed the current size of the stack.
πŸ”€ setRoutes

βš›οΈ (transform: SetRoutesTransformCallback, animated?: boolean = false) => Promise<void>

πŸ“Œ transform: SetRoutesTransformCallback
πŸ“Œ NavRouteStackPartialItem
Allows for the manipulation of the current routes in the navigation stack. Amongst all the navigation commands, this is the most flexible (and complex) because it allows you to add, remove, reorder, replace, or completely change the current active routes in navigation stack.

The transform parameter accepts a function callback that, when called, will receive an array of objects that represents the current active routes in the navigation stack.

The transform callback must then return an array of route objects that will be used to set the new navigation stack (i.e. the new routes that will replace the current active routes).

Any of the previous active routes that are not returned from the transform callback will be removed from the navigation stack, and conversely, any new routes that weren't in the previous active routes will be created, and then added to the navigation stack.

πŸ“ Note: The transform callback will receive an array of NavRouteStackPartialItem objects that represents the current active routes in the navigation stack. This object has an optional property called routeID. The number value in the routeID property is auto-generated internally, and acts as a unique identifier for a route (as such, existing active routes in the navigation stack will have an existing associated routeID).

If the transform callback returns a NavRouteStackPartialItem object that does not have a routeID, then it means that it's a new route (i.e. it will create a new route based on that object, and then add it to the navigation stack).

Conversely, in order to "preserve" an active route and let it remain in the navigation stack, then simply return that route's corresponding object from the NavRouteStackPartialItem items along with its associated routeID value.

πŸ’‘ Tip: This command is useful if you need complete control over the navigation stack. Amongst all the other navigation commands, this is the most direct mapping to UINavigationController.setViewControllers. Jump to the setRoutes guides section for usage examples.
πŸ”€ setNavigationBarHidden

βš›οΈ (isHidden: boolean, animated: boolean) => Promise<void>
Programmatically shows or hides the navigation bar. Maps to the UINavigationController.setNavigationBarHidden method.

πŸ’‘ Tip: If you want to immediately hide the navigation bar when a route is pushed (i.e. you don't want the navigation bar to be visible when that route is pushed), you can use the RouteOptions.navigationBarVisibility property instead.

The navigationBarVisibility property can either be set via routeOptionsDefault (which can be found in the route's config in the NavigatorView.routes prop), or via the RouteViewPortal component using the RouteViewPortal.routeOptions prop.

πŸ’‘ Tip: Like all the other navigation commands, this command is also async. So this command is useful if you want to wait for the navigation bar hide animation to finish first before doing something else.

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.

Name and Type Description
πŸ”€ replacePreviousRoute

βš›οΈ (routeItem: NavRouteItem, animated?: boolean = false) => Promise<void>

πŸ“Œ routeItem: NavRouteItem
Replaces the previous route in the navigation stack with a new route.
πŸ”€ replaceCurrentRoute

βš›οΈ (routeItem: NavRouteItem, animated?: boolean = false) => Promise<void>

πŸ“Œ routeItem: NavRouteItem
Replaces the current route (i.e. the topmost route) in the navigation stack with a new route.
πŸ”€ removePreviousRoute

βš›οΈ (animated?: boolean = false) => Promise<void>
Removes the previous route in the navigation stack.
πŸ”€ removeAllPrevRoutes

βš›οΈ (animated?: boolean = false) => Promise<void>
Removes all of the previous routes in the navigation stack.

NavigatorView Misc. Convenience Commands

TBA

Name and Type Description
πŸ”€ getRouteStackItemForCurrentRoute

βš›οΈ () => NavRouteStackItem Β¦ undefined

πŸ“Œ NavRouteStackItem
TBA

πŸ“ Note: Internally, this command uses the getMatchingRouteStackItem command to get the navigation stack item for the current active route.
πŸ”€ getRouteStackItemForPreviousRoute

βš›οΈ () => NavRouteStackItem Β¦ undefined

πŸ“Œ NavRouteStackItem
TBA

πŸ“ Note: Internally, this command uses the getMatchingRouteStackItem command to get the navigation stack item for the previous active route.
πŸ”€ getNavigationObjectForCurrentRoute

βš›οΈ () => NavigationObject Β¦ undefined

πŸ“Œ NavigationObject
TBA

πŸ“ Note: Internally, this command uses the getNavigationObjectForRoute command to get the navigation object for the current active route.
πŸ”€ getNavigationObjectForPreviousRoute

βš›οΈ () => NavigationObject Β¦ undefined

πŸ“Œ NavigationObject
TBA

πŸ“ Note: Internally, this command uses the getNavigationObjectForRoute command to get the navigation object for the previous active route
πŸ”€ setRouteOptionsForRoute

βš›οΈ (routeDetails: NavRouteStackItemPartialMetadata, routeOptions: RouteOptions) => Promise<void>

πŸ“Œ routeDetails: NavRouteStackItemPartialMetadata
πŸ“Œ routeOptions: RouteOptions
TBA

πŸ“ Note: Internally, this uses the route's navigation object to apply the route options (i.e. this command is equivalent to using the NavigationObject.setRouteOptions route command).

πŸ“ Note: Internally, this command uses the getNavigationObjectForRoute command to get the route's matching NavigationObject. It then uses the navigation object to call NavigationObject.setRouteOptions.
πŸ”€ getRouteOptionsForRoute

βš›οΈ () => RouteOptions Β¦ undefined

πŸ“Œ RouteOptions
TBA

πŸ“ Note: Internally, this command uses the getNavigationObjectForRoute command to get the navigation object for the corresponding route. It then returns the value in NavigationObject.routeOptions.
πŸ”€ setRouteOptionsForCurrentRoute

βš›οΈ (routeOptions: RouteOptions) => Promise<void>

πŸ“Œ routeOptions: RouteOptions
TBA

πŸ“ Note: Internally, this uses the route's navigation object to apply the route options (i.e. this command is equivalent to using the NavigationObject.setRouteOptions route command).

πŸ“ Note: Internally, this uses the getNavigationObjectForCurrentRoute command to get the navigation object for the current active route. It then uses the navigation object to call NavigationObject.setRouteOptions.
πŸ”€ getRouteOptionsForCurrentRoute

βš›οΈ () => RouteOptions Β¦ undefined

πŸ“Œ RouteOptions
TBA

πŸ“ Note: Internally, this command uses the getNavigationObjectForRoute command to get the navigation object for the current active route. It then returns the value in NavigationObject.routeOptions.
πŸ”€ setRouteOptionsForPreviousRoute

βš›οΈ (routeOptions: RouteOptions) => Promise<void>

πŸ“Œ routeOptions: RouteOptions
TBA

πŸ“ Note: Internally, this uses the route's navigation object to apply the route options (i.e. this command is equivalent to using the NavigationObject.setRouteOptions route command).

πŸ“ Note: Internally, this uses the getNavigationObjectForPreviousRoute command to get the navigation object for the previous active route It then uses the navigation object to call NavigationObject.setRouteOptions.
πŸ”€ getRouteOptionsForPreviousRoute

βš›οΈ () => RouteOptions Β¦ undefined

πŸ“Œ RouteOptions
TBA

πŸ“ Note: Internally, this command uses the getNavigationObjectForRoute command to get the navigation object for the previous active route. It then returns the value in NavigationObject.routeOptions.

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
Prop Name and Type Description
πŸ”€ routeOptions

βš›οΈ RouteOptions
This prop will override the existing route options that were provided either from: 1️⃣ the route's "route config" in the NavigatorView.routes prop (i.e. NavRouteConfigItem.routeOptionsDefault),
2️⃣ the route options provided in the NavigatorView.initialRoutes prop (i.e. NavRouteItem.routeOptions), or
3️⃣ the route options override provided via a navigation command (e.g. navigation.push({..., routeOptions: {...}})).

πŸ“ Note A: The route options provided via this prop can be potentially be overridden by the navigation.setRouteOptions command.

πŸ“ Note B: Internally, this prop is basically just setting the route options for the current route on your behalf whenever you provide a new value (or when the said value changes).

πŸ’‘ Tip: This prop is useful for dynamically changing the current route options based on some condition.

For example, you can change the navigation bar title after loading a resource, or temporarily hide the back button while loading, etc.

πŸ“Œ Related Sections:
β€’ RouteOptions Precedence
πŸ”€ renderNavBarLeftItem

βš›οΈ (navigation) => ReactElement
This prop is used for rendering a custom left item component in the navigation bar.

If leftItemsSupplementBackButton in routeOptions is set to true (which it is by default), then it will replace the back button (i.e. the back button will not be shown).

πŸ“ Note: If this prop is used, it'll implicitly set navBarButtonLeftItemsConfig to { type: 'CUSTOM' } for a route's routeOptions. So if the navBarButtonLeftItemsConfig is explicitly set to anything other than "custom", then this prop will not do anything.
πŸ”€ renderNavBarRightItem

βš›οΈ (navigation: NavigationObject) => ReactElement
This prop is used for rendering a custom right item component in the navigation bar.

πŸ“ Note: If this prop is used, it'll implicitly set navBarButtonRightItemsConfig to { type: 'CUSTOM' } for a route's routeOptions. So if the navBarButtonRightItemsConfig is explicitly set to anything other than "custom", then this prop will not do anything.
πŸ”€ renderNavBarTitleItem

βš›οΈ (navigation: NavigationObject) => ReactElement
This prop is used for rendering a custom title item component in the navigation bar.

πŸ’‘ Tip: You can access the route's routeTitle via the navigation object (i.e. navigation.routeOptions.routeTitle).
πŸ”€ renderRouteHeader

βš›οΈ (navigation: NavigationObject) => ReactElement
This prop allows you to render a header at the top of the screen (check out NavigatorShowcase01 and NavigatorShowcase02 for examples).

This prop accepts a function that must return a RouteHeaderView as the root element. This component integrates with the route in the native side to enable the header behavior. Check the documentation for RouteHeaderView for more details.

RouteViewPortal Example

RouteViewPortalExample01

// πŸ“ 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.





  • Search Bar-Related Events
    • onUpdateSearchResults
    • onWillDismissSearchController
    • onDidDismissSearchController
    • onWillPresentSearchController
    • onDidPresentSearchController
    • 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.


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
Prop Name and Type Description
πŸ”€ Required: config

βš›οΈ RouteHeaderConfig
TBA
πŸ”€ headerTopPadding

βš›οΈ HeaderHeightConfig
TBA
πŸ”€ style

βš›οΈ ViewStyle
TBA

D.2. Context

D.2.1. NavigationContext

TBA

Name and Type Description
πŸ”€ routeID

βš›οΈ number
TBA
πŸ”€ navigatorID

βš›οΈ number
TBA
πŸ”€ navigation

βš›οΈ NavigationObject
TBA

D.2.2. NavigatorUIConstantsContext

TBA

Name and Type Description
πŸ”€ navigatorID

βš›οΈ number
TBA
πŸ”€ safeAreaInsets

βš›οΈ EdgeInsets
TBA
πŸ”€ statusBarHeight

βš›οΈ number
TBA
πŸ”€ navigatorSize

βš›οΈ Rect
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

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.

Enum Key and Event Type Description
πŸ”€ onRouteWillPush

βš›οΈ OnRoutePushEvent

πŸ“Œ OnRoutePushEventObject
An event that is triggered when the current route is about to be pushed into the navigation stack (i.e. the push transition has begun).

πŸ“Œ Internally, this event is triggered just before the UINavigationController.pushViewController method is called.
πŸ”€ onRouteDidPush

βš›οΈ OnRoutePushEvent

πŸ“Œ OnRoutePushEventObject
An event that is triggered when the current route has been pushed into the navigation stack (i.e. the push transition has ended). This event fires after onRouteWillPush.

πŸ“Œ Internally, this event is triggered inside the completion block of the UINavigationController.pushViewController method.
πŸ”€ onRouteWillPop

βš›οΈ OnRoutePopEvent

πŸ“Œ OnRoutePopEventObject
An event that is triggered when a route is about to be popped from the navigation stack (i.e. the pop transition has begun).

πŸ“Œ Internally, this event is triggered by the UIViewController.willMove lifecycle method.

πŸ’‘ Tip: The event.nativeEvent object has a property called isUserInitiated. This property specifies whether the pop transition was initiated by the navigation command (false), or if it was initiated by the user (e.g. via the back button or swipe back gesture) (true).
πŸ”€ onRouteDidPop

βš›οΈ OnRoutePopEvent

πŸ“Œ OnRoutePopEventObject
An event that is triggered when a route has been popped from the navigation stack (i.e. the pop transition has ended). This event fires after onRouteWillPop.

πŸ“Œ Internally, this event is triggered by the UIViewController.didMove lifecycle method.

πŸ’‘ Tip: The event.nativeEvent object has a property called isUserInitiated. This property specifies whether the pop transition was initiated by the navigation command (false), or if it was initiated by the user (e.g. via the back button or swipe back gesture) (true).

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).

Enum Key and Event Type Description
πŸ”€ onRouteWillFocus

βš›οΈ OnRouteFocusBlurEvent

πŸ“Œ OnRouteFocusBlurEventObject
An event that is triggered when the current route is about to become in focus (i.e. the pop transition for the topmost route item has begun).

πŸ“Œ Internally, this event is triggered by the UIViewController.viewWillAppear lifecycle method.

πŸ“ Note: This event will also fire alongside onRouteWillPush (i.e. when the current route is about to become visible for the first time).
πŸ”€ onRouteDidFocus

βš›οΈ OnRouteFocusBlurEvent

πŸ“Œ OnRouteFocusBlurEventObject
An event that is triggered when the current route has received focus (i.e. the pop transition for the topmost route item has ended).

πŸ“Œ Internally, this event is triggered by the UIViewController.viewDidAppear lifecycle method.

πŸ“ Note: This event will also fire alongside onRouteDidPush (i.e. when the current route has become visible for the first time).
πŸ”€ onRouteWillBlur

βš›οΈ OnRouteFocusBlurEvent

πŸ“Œ OnRouteFocusBlurEventObject
An event that is triggered when the current route is about to lose focus (i.e. a new route is about to be pushed into the navigation stack).

πŸ“Œ Internally, this event is triggered by the UIViewController.viewWillDisappear lifecycle method.

πŸ“ Note: This event will fire alongside onRouteWillPop (i.e. when the current route is about to be popped from the navigation stack).
πŸ”€ onRouteDidBlur

βš›οΈ OnRouteFocusBlurEvent

πŸ“Œ OnRouteFocusBlurEventObject
An event that is triggered when the current route has lost focus (i.e. a new route has been pushed into the navigation stack).

πŸ“Œ Internally, this event is triggered by the UIViewController.viewDidDisappear lifecycle method.

πŸ“ Note: This event will fire alongside onRouteDidPop (i.e. when the current route has been 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).
Enum Key and Event Type Description
πŸ”€ onPressNavBarLeftItem

βš›οΈ OnPressNavBarItemEvent

πŸ“Œ OnPressNavBarItemEventObject
An event that is triggered when a navigation bar left item is pressed.
πŸ”€ onPressNavBarRightItem

βš›οΈ OnPressNavBarItemEvent

πŸ“Œ OnPressNavBarItemEventObject
An event that is triggered when a navigation bar right item is pressed.

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.

Enum Key and Event Type Description
πŸ”€ onUpdateSearchResults

βš›οΈ OnUpdateSearchResultsEvent

πŸ“Œ OnUpdateSearchResultsEventObject
An event that is triggered whenever the search bar's text changes.

πŸ“Œ Internally, this event is triggered by the UISearchResultsUpdating.updateSearchResults method.

πŸ’‘ Tip: This event is useful for updating a list of results. The event.nativeEvent object will contain the search bar's current text value. Use the search text value to update the list accordingly.
πŸ”€ onWillDismissSearchController

βš›οΈ OnWillDismissSearchControllerEvent

πŸ“Œ OnWillDismissSearchControllerEventObject
TBA

πŸ“Œ Internally, this event is triggered by the UISearchControllerDelegate.willDismissSearchController method.
πŸ”€ onDidDismissSearchController

βš›οΈ OnDidDismissSearchControllerEvent

πŸ“Œ OnDidDismissSearchControllerEventObject
TBA

πŸ“Œ Internally, this event is triggered by the UISearchControllerDelegate.didDismissSearchController method.
πŸ”€ onWillPresentSearchController

βš›οΈ OnWillPresentSearchControllerEvent

πŸ“Œ OnWillPresentSearchControllerEventObject
TBA

πŸ“Œ Internally, this event is triggered by the UISearchControllerDelegate.willPresentSearchController method.
πŸ”€ onDidPresentSearchController

βš›οΈ OnDidPresentSearchControllerEvent

πŸ“Œ OnDidPresentSearchControllerEventObject
TBA

πŸ“Œ Internally, this event is triggered by the UISearchControllerDelegate.didPresentSearchController method.
πŸ”€ onSearchBarCancelButtonClicked

βš›οΈ OnSearchBarCancelButtonClickedEvent

πŸ“Œ OnSearchBarCancelButtonClickedEventObject
An event that is triggered when the search bar's cancel button is pressed.

When the cancel button is pressed, the search bar's text field will be cleared (this will trigger onUpdateSearchResults).

πŸ“Œ Internally, this event is triggered by the UISearchBarDelegate.searchBarCancelButtonClicked method.

πŸ“ Note: The search bar's cancel button will only appear when the search bar is in focus (unless specified otherwise via the RouteSearchControllerConfig.automaticallyShowsCancelButton property in the route's search config).
πŸ”€ onSearchBarSearchButtonClicked

βš›οΈ onSearchBarSearchButtonClickedEvent

πŸ“Œ OnSearchBarSearchButtonClickedEventObject
An event that is triggered when the search button (i.e the return key) is pressed in the iOS keyboard while the search bar is in focus.

πŸ“Œ Internally, this event is triggered by the UISearchBarDelegate.searchBarSearchButtonClicked method.

πŸ’‘ Tip: The keyboard's return key label can modified via the search config (i.e. RouteSearchControllerConfig.returnKeyType).

πŸ“„ 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.

Name and Type Description
πŸ”€ isNativeRoute?

βš›οΈ false Β¦ undefined
Used to identify whether the config provided is a "JS/React" route, or a "native" route. This property is optional, you don't have to provide a value.

Since this type is used to create "JS/React" route, you can only explicitly set this property to false or undefined.
πŸ”€ initialRouteProps?

βš›οΈ object
Configures the initial "route props" that the route will receive.

πŸ“ Note A: The initialRouteProps will be merged and potentially overridden by the following:
1️⃣ NavigatorView.initialRoutes prop (i.e. NavRouteItem.routeProps).
2️⃣ Via a navigation command, e.g. push({...routeProps: {...}}).

πŸ“ Note B: The route's "route props" can be accessed via NavigationObject.routeProps (see "The NavigationObject" section for examples on how to get the route's navigation object).
πŸ”€ routeOptionsDefault?

βš›οΈ RouteOptions
Used to set the initial "route options" that the route will receive.

πŸ“ Note: The default route options provided will be merged and potentially overridden by the following:
1️⃣ NavigatorView.initialRoutes prop (i.e. NavRouteItem.routeOptions).
2️⃣ Via a navigation command, e.g. push({...routeOptions: {...}}).
3️⃣ Using the route's NavigationObject.setRouteOptions(...) command.
4️⃣ Or through the RouteViewPortal.routeOptions prop.
πŸ”€ Required: renderRoute

βš›οΈ (routeItem: NavRouteItem) => ReactElement<RouteContentProps>

πŸ“Œ routeItem: NavRouteItem

πŸ“Œ RouteContentProps
Configures what component to show when the route becomes active.

This property accepts a function that returns a react element. The function you pass in will receive a NavRouteItem object. The react element returned by the function will be shown when the route becomes active.

The react element that you returned will implicitly receive RouteContentProps. In other words, your route will receive the NavigationObject via props (i.e. props.navigation).

Alternatively, you can also get the NavigationObject via NavigationContext, or through using the useNavRouteEvents hook (see "The NavigationObject" section for examples).
πŸ”€ renderNavBarLeftItem?

βš›οΈ RenderNavItem i.e. (navigation: NavigationObject) => ReactElement Β¦ null Β¦ undefined

πŸ“Œ navigation: NavigationObject
Configures what custom react component to show on the left side of navigation bar when the route becomes active.

This property accepts a function that returns a react element. The function will receive the NavigationObject as an argument. The returned element will be rendered on the left side of the navigation bar.

πŸ“ Note A: This property overrides the NavigatorView.renderNavBarLeftItem prop. This property can be overridden via the route's RouteViewPortal.renderNavBarLeftItem prop.

πŸ“ Note B: If this property is set, it'll implicitly set RouteOptions.navBarButtonLeftItemsConfig to { type: 'CUSTOM' } for a route's routeOptions.

In other words, if the navBarButtonLeftItemsConfig property is explicitly set to anything other than "custom", then this prop will not do anything (i.e. no custom component will be rendered for the navigation bar's left item).

πŸ“ Note C: Pressing the custom navigation bar left item component will not trigger the onPressNavBarLeftItem event. Handle the touch event yourself (e.g. via a <Button/>-like component).

πŸ“ Note D: If a route's RouteOptions.leftItemsSupplementBackButton is set to false (which it isn't by default), then it will replace the back button (i.e. the back button will not be shown).
πŸ”€ renderNavBarRightItem?

βš›οΈ RenderNavItem i.e. (navigation: NavigationObject) => ReactElement Β¦ null Β¦ undefined

πŸ“Œ navigation: NavigationObject
Configures what custom react component to show on the right side of navigation bar when the route becomes active.

This property accepts a function that returns a react element. The function will receive the NavigationObject as an argument. The returned element will be rendered on the left side of the navigation bar.

πŸ“ Note A: This property overrides the NavigatorView.renderNavBarRightItem prop. This property can be overridden via the route's RouteViewPortal.renderNavBarRightItem prop.

πŸ“ Note B: If this property is set, it'll implicitly set RouteOptions.navBarButtonRightItemsConfig to { type: 'CUSTOM' } for a route's routeOptions.

In other words, if the navBarButtonRightItemsConfig property is explicitly set to anything other than "custom", then this prop will not do anything (i.e. no custom component will be rendered for the navigation bar's left item).

πŸ“ Note C: Pressing the custom navigation bar right item component will not trigger the onPressNavBarRightItem event. Handle the touch event yourself (e.g. via a <Button/>-like component).
πŸ”€ renderNavBarTitleItem?

βš›οΈ RenderNavItem i.e. (navigation: NavigationObject) => ReactElement Β¦ null Β¦ undefined

πŸ“Œ navigation: NavigationObject
Configures what custom react component to show for the navigation bar's title when the route becomes active.

This property accepts a function that returns a react element. The function will receive the NavigationObject as an argument. The returned element will be rendered in the middle of the navigation bar (i.e. as a replacement for the navigation bar title).

πŸ“ Note: This property overrides the NavigatorView.renderNavBarTitleItem prop. This property can be overridden via the route's RouteViewPortal.renderNavBarTitleItem prop.

πŸ’‘ Tip: You can access the route's routeTitle via the navigation object (i.e. navigation.routeOptions.routeTitle).

Object Type: NavRouteConfigItemNative

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

Name and Type Description
πŸ”€ Required: isNativeRoute

βš›οΈ true
Used to identify whether the config provided is a "JS/React" route, or a "native" route. This property must be explicitly set to true.

Since this type is used to create "native" route, you must explicitly set this property to true.
πŸ”€ initialRouteProps?

βš›οΈ object
Configures the initial "route props" that the native route will receive.

πŸ“ Note A: The initialRouteProps will be merged and potentially overridden by the following:
1️⃣ NavigatorView.initialRoutes prop (i.e. NavRouteItem.routeProps).
2️⃣ Via a navigation command, e.g. push({...routeProps: {...}}).

πŸ“ Note B: The native route (i.e. the RNINavigatorRouteBaseViewController instance) can access the "route props" via self.routeProps property.

πŸ“„ RouteOptions.ts

Object Type: RouteOptions

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


RouteOptions: General Properties
Name and Type Description
πŸ”€ statusBarStyle?

βš›οΈ StatusBarStyle
TBA

πŸ“Œ Maps to UIStatusBarStyle enum in the apple docs.
πŸ”€ routeContainerStyle?

βš›οΈ ViewStyle
Whatever component you return from renderRoutes will be wrapped inside a "route container" view. This prop allows you to set the style of that view.

πŸ’‘ Tip: You can use this prop to provide a default background color for all the routes.
πŸ”€ automaticallyAddHorizontalSafeAreaInsets?

βš›οΈ boolean
TBA

RouteOptions: Transition Config-Related Properties
Name and Type Description
πŸ”€ transitionConfigPush?

βš›οΈ RouteTransitionConfig
TBA
πŸ”€ transitionConfigPop?

βš›οΈ RouteTransitionConfig
TBA

RouteOptions: Navigation Bar Config-Related Properties
Name and Type Description
πŸ”€ routeTitle?

βš›οΈ string
TBA

πŸ“Œ Maps to UINavigationItem.title property in the apple docs.
πŸ”€ prompt?

βš›οΈ string
TBA

πŸ“Œ Maps to UINavigationItem.prompt property in the apple docs.
πŸ”€ largeTitleDisplayMode?

βš›οΈ LargeTitleDisplayMode
TBA

πŸ“Œ Maps to UINavigationItem.largeTitleDisplayMode property, and the UINavigationItem.LargeTitleDisplayMode enum in the apple docs.
πŸ”€ searchBarConfig?

βš›οΈ RouteSearchControllerConfig
TBA

πŸ“ Note: The object provided is used to configure a UISearchController + UISearchBar instance in the native-side.

πŸ“Œ Maps to UINavigationItem.searchController property in the apple docs.

RouteOptions: Navigation Bar Item Config-Related Properties
Name and Type Description
πŸ”€ navBarButtonBackItemConfig?

βš›οΈ NavBarBackItemConfig
TBA
πŸ”€ navBarButtonLeftItemsConfig?

βš›οΈ NavBarItemsConfig
TBA

πŸ“Œ Maps to UINavigationItem.leftBarButtonItems property in the apple docs.
πŸ”€ navBarButtonRightItemsConfig?

βš›οΈ NavBarItemsConfig
TBA

πŸ“Œ Maps to UINavigationItem.rightBarButtonItems property in the apple docs.

RouteOptions: Navigation Bar Back Item Config-Related Properties
Name and Type Description
πŸ”€ backButtonTitle?

βš›οΈ string
TBA

πŸ“Œ Maps to UINavigationItem.backButtonTitle property in the apple docs.
πŸ”€ hidesBackButton?

βš›οΈ boolean
TBA

πŸ“Œ Maps to UINavigationItem.hidesBackButton property in the apple docs.
πŸ”€ backButtonDisplayMode?

βš›οΈ BackButtonDisplayMode
TBA

πŸ“Œ Maps to UINavigationItem.backButtonDisplayMode property, and UINavigationItem.BackButtonDisplayMode enum in the apple docs.
πŸ”€ leftItemsSupplementBackButton?

βš›οΈ boolean
TBA

πŸ“Œ Maps to UINavigationItem.leftItemsSupplementBackButton property in the apple docs.
πŸ”€ applyBackButtonConfigToCurrentRoute?

βš›οΈ boolean

✳️ Default: false
TBA

RouteOptions: Override-related Properties
Name and Type Description
πŸ”€ navBarAppearanceOverride?

βš›οΈ NavBarAppearanceCombinedConfig
TBA
πŸ”€ navigationBarVisibility?

βš›οΈ NavigationBarVisibilityMode
TBA
πŸ”€ allowTouchEventsToPassThroughNavigationBar?

βš›οΈ boolean
TBA

πŸ“„ NavigationObject.ts

Object Type: NavigationObject

TBA

NavigationObject: General Properties
Name and Type Description
πŸ”€ routeID

βš›οΈ string
TBA
πŸ”€ routeKey

βš›οΈ string
TBA
πŸ”€ routeIndex

βš›οΈ number
TBA
πŸ”€ routeProps

βš›οΈ object
TBA
πŸ”€ routeOptions

βš›οΈ RouteOptions
TBA

NavigationObject: Navigation Commands

See "NavigatorView Navigation Commands" section for more info.

Name and Type Description
πŸ”€ push

βš›οΈ (routeItem, options?) => Promise<void>
Maps to the NavigatorView.push command.
πŸ”€ pop

βš›οΈ (options?) => Promise<void>
Maps to the NavigatorView.pop command.
πŸ”€ popToRoot

βš›οΈ (options?) => Promise<void>
Maps to the NavigatorView.popToRoot command.
πŸ”€ removeRoute

βš›οΈ (routeIndex: number, animated?: boolean = false) => Promise<void>
Maps to the NavigatorView.removeRoute command.
πŸ”€ removeRoutes

βš›οΈ (routeIndices: number, animated?: boolean = false) => Promise<void>
Maps to the NavigatorView.removeRoutes command.
πŸ”€ replaceRoute

βš›οΈ (prevRouteIndex: number, routeItem: NavRouteItem, animated?: boolean = false) => Promise<void>
Maps to the NavigatorView.replaceRoute command.
πŸ”€ insertRoute

βš›οΈ (routeItem: NavRouteItem, atIndex: number, animated?: boolean = false) => Promise<void>
Maps to the NavigatorView.insertRoute command.
πŸ”€ setRoutes

βš›οΈ (transform: SetRoutesTransformCallback, animated?: boolean = false) => Promise<void>
Maps to the NavigatorView.setRoutes command.
πŸ”€ setNavigationBarHidden

βš›οΈ (isHidden: boolean, animated: boolean) => Promise<void>
Maps to the NavigatorView.setNavigationBarHidden command.

NavigationObject: Convenience Navigation Commands

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

Name and Type Description
πŸ”€ replacePreviousRoute

βš›οΈ (routeItem: NavRouteItem, animated?: boolean = false) => Promise<void>
Maps to the NavigatorView.replacePreviousRoute command.
πŸ”€ replaceCurrentRoute

βš›οΈ (routeItem: NavRouteItem, animated?: boolean = false) => Promise<void>
Maps to the NavigatorView.replaceCurrentRoute command.
πŸ”€ removePreviousRoute

βš›οΈ (animated?: boolean = false) => Promise<void>
Maps to the NavigatorView.removePreviousRoute command.
πŸ”€ removeAllPrevRoutes

βš›οΈ (animated?: boolean = false) => Promise<void>
Maps to the NavigatorView.removeAllPrevRoutes command.

NavigationObject: General/Misc. Navigation Commands

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

Name and Type Description
πŸ”€ getActiveRoutes

βš›οΈ () => Array<NavRouteStackItem>
Maps to the NavigatorView.getActiveRoutes command.
πŸ”€ sendCustomCommandToNative

βš›οΈ (commandKey: string, commandData: object Β¦ null) => Promise<object Β¦ null>
Maps to the NavigatorView.sendCustomCommandToNative command.
πŸ”€ getNavigatorConstants

βš›οΈ () => Promise<NavigatorConstantsObject>
Maps to the NavigatorView.getNavigatorConstants command.
πŸ”€ dismissModal

βš›οΈ (animated: Bool) => Promise<void>
Maps to the NavigatorView.dismissModal command.
πŸ”€ getMatchingRouteStackItem

βš›οΈ (routeDetails: NavRouteStackItemPartialMetadata) => NavRouteStackItem Β¦ undefined
Maps to the NavigatorView.getMatchingRouteStackItem command.
πŸ”€ getNavigationObjectForRoute

βš›οΈ (routeDetails: NavRouteStackItemPartialMetadata) => NavigationObject Β¦ undefined
Maps to the NavigatorView.getNavigationObjectForRoute command.

NavigationObject: Misc. Convenience Commands

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

Name and Type Description
πŸ”€ getRouteStackItemForCurrentRoute

βš›οΈ () => NavRouteStackItem Β¦ undefined
Maps to the NavigatorView.getRouteStackItemForCurrentRoute command.
πŸ”€ getRouteStackItemForPreviousRoute

βš›οΈ () => NavRouteStackItem Β¦ undefined
Maps to the NavigatorView.getRouteStackItemForPreviousRoute command.
πŸ”€ getNavigationObjectForCurrentRoute

βš›οΈ () => NavigationObject Β¦ undefined
Maps to the NavigatorView.getNavigationObjectForCurrentRoute command.
πŸ”€ getNavigationObjectForPreviousRoute

βš›οΈ () => NavigationObject Β¦ undefined
Maps to the NavigatorView.getNavigationObjectForPreviousRoute command.
πŸ”€ setRouteOptionsForRoute

βš›οΈ (routeDetails: NavRouteStackItemPartialMetadata, routeOptions: RouteOptions) => Promise<void>
Maps to the NavigatorView.setRouteOptionsForRoute command.
πŸ”€ getRouteOptionsForRoute

βš›οΈ () => RouteOptions Β¦ undefined
Maps to the NavigatorView.getRouteOptionsForRoute command.
πŸ”€ setRouteOptionsForCurrentRoute

βš›οΈ (routeOptions: RouteOptions) => Promise<void>
Maps to the NavigatorView.setRouteOptionsForCurrentRoute command.
πŸ”€ getRouteOptionsForCurrentRoute

βš›οΈ () => RouteOptions Β¦ undefined
Maps to the NavigatorView.getRouteOptionsForCurrentRoute command.
πŸ”€ setRouteOptionsForPreviousRoute

βš›οΈ (routeOptions: RouteOptions) => Promise<void>
Maps to the NavigatorView.setRouteOptionsForPreviousRoute command.
πŸ”€ getRouteOptionsForPreviousRoute

βš›οΈ () => RouteOptions Β¦ undefined
Maps to the NavigatorView.getRouteOptionsForPreviousRoute command.

NavigationObject: Route Commands
Name and Type Description
πŸ”€ getRouteOptions

βš›οΈ () => RouteOptions
TBA
πŸ”€ setRouteOptions

βš›οΈ `(routeOptions: RouteOptions
null) => void`
πŸ”€ setHidesBackButton

βš›οΈ (isHidden: boolean, animated: boolean) => void
TBA
πŸ”€ getRouteConstants

βš›οΈ () => Promise<RouteConstantsObject>

πŸ“Œ RouteConstantsObject
TBA
πŸ”€ getRouteSearchControllerState

βš›οΈ () => Promise<RouteSearchControllerState>

πŸ“Œ RouteSearchControllerState
TBA

πŸ“ Note: Command will fail if the current route does not have a search config (i.e. RouteOptions.searchBarConfig), so make sure to provide a search config first.

πŸ’‘ Tip: You can use this command to get the current text in the search bar, see whether the search bar is active or not, etc.
πŸ”€ setRouteSearchControllerState

βš›οΈ (state: Partial<RouteSearchControllerState>) => Promise<void>

πŸ“Œ RouteSearchControllerState
TBA

πŸ“ Note: Command will fail if the current route does not have a search config (i.e. RouteOptions.searchBarConfig), so make sure to provide a search config first.

πŸ’‘ Tip: You can use this command to set the current text in the search bar, toggle whether the search bar is active, etc.

NavigationObject: "Get Ref" Commands
Name and Type Description
πŸ”€ getRefToRoute

βš›οΈ () => NavigatorRouteView
TBA
πŸ”€ getRefToNavigator

βš›οΈ () => NavigatorView
TBA
πŸ”€ getRefToNavRouteEmitter

βš›οΈ () => NavigatorRouteViewEventEmitter
TBA

πŸ“„ NavRouteItem.ts

Object Type: NavRouteItem

TBA

Name and Type Description
πŸ”€ Required: routeKey

βš›οΈ string
TBA
πŸ”€ routeProps?

βš›οΈ object
TBA
πŸ”€ routeOptions?

βš›οΈ RouteOptions
TBA

Object Type: NavRouteStackItem

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

Name and Type Description
πŸ”€ Required: routeKey

βš›οΈ string
Same as NavRouteItem.routeKey.
πŸ”€ routeProps?

βš›οΈ object
Same as NavRouteItem.routeProps.
πŸ”€ routeOptions?

βš›οΈ RouteOptions
Same as NavRouteItem.routeOptions.
πŸ”€ routeID

βš›οΈ number
TBA
πŸ”€ routeIndex

βš›οΈ number
TBA
πŸ”€ isNativeRoute

βš›οΈ boolean
TBA

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.

Name and Type Description
🀝 Extends NavRouteStackItem Shares the same properties from NavRouteStackItem (and NavRouteItem).
πŸ”€ routeID?

βš›οΈ number
TBA

Object Type: NavRouteStackItemMetadata

Contains properties that can be used to identify an active route in the navigation stack.

Name and Type Description
πŸ”€ routeID

βš›οΈ abc
TBA
πŸ”€ routeKey

βš›οΈ abc
TBA
πŸ”€ routeIndex

βš›οΈ abc
TBA

Object Type: NavRouteStackItemMetadata

Is essentially identical to the NavRouteStackItemMetadata type, except all the properties are optional (i.e. equivalent to Partial<NavRouteStackItemMetadata> in typescript).


πŸ“„ 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
Name and Type Description
πŸ”€ navBarPreset?

βš›οΈ NavBarPreset e.g. 'none' Β¦ 'noShadow' Β¦ 'clearBackground'

✳️ Default: none
TBA
πŸ”€ barStyle?

βš›οΈ BarStyle e.g.'default' Β¦ 'black'
TBA

πŸ“Œ Maps to UINavigationBar.barStyle property in the apple docs.
πŸ”€ titleTextAttributes?

βš›οΈ TextStyle
TBA

πŸ“Œ Maps to UINavigationBar.titleTextAttributes property in the apple docs.
πŸ”€ largeTitleTextAttributes?

βš›οΈ TextStyle
TBA

πŸ“Œ Maps to UINavigationBar.largeTitleTextAttributes property in the apple docs.
πŸ”€ titleVerticalPositionAdjustment?

βš›οΈ { [key in BarMetrics]?: number }

πŸ“Œ BarMetrics
TBA

πŸ“Œ Maps to UINavigationBar.setTitleVerticalPositionAdjustment method in the apple docs.
πŸ”€ tintColor?

βš›οΈ string Β¦ DynamicColor
TBA

πŸ“Œ Maps to UINavigationBar.tintColor property in the apple docs.
πŸ”€ barTintColor?

βš›οΈ string Β¦ DynamicColor
TBA

πŸ“ Note: Starting on iOS 15+, when there is no content behind the navigation bar (i.e. when the scroll position is all the way to the top), the navigation bar will not have a background (e.g. the navigation bar is completely see through). The only way to set a background is via explicitly providing a appearance config to scrollEdgeAppearance.

πŸ“Œ Maps to UINavigationBar.barTintColor property in the apple docs.
πŸ”€ backIndicatorImage?

βš›οΈ ImageItemConfig
TBA

πŸ“Œ Maps to UINavigationBar.backIndicatorImage property in the apple docs.
πŸ”€ backgroundImage?

βš›οΈ { [key in BarMetrics]?: ImageItemConfig }

πŸ“Œ BarMetrics
πŸ“Œ ImageItemConfig
TBA

πŸ“Œ Maps to UINavigationBar.setBackgroundImage method in the apple docs.
πŸ”€ shadowImage?

βš›οΈ ImageItemConfig
TBA

πŸ“ Note: A custom background image must also be set for the shadow image to take affect. As mentioned in the apple docs: "To show a custom shadow image, you must also set a custom background image".

πŸ“Œ Maps to UINavigationBar.shadowImage property in the apple docs.

Object Type: NavBarAppearanceConfig

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

Name and Type Description
πŸ”€ navBarPreset?

βš›οΈ NavBarPreset i.e. 'none' Β¦ 'noShadow' Β¦ 'clearBackground'

✳️ Default: none
TBA
πŸ”€ useStandardAppearanceAsDefault?

βš›οΈ boolean

✳️ Default: false
TBA
πŸ”€ standardAppearance?

βš›οΈ NavBarAppearance
TBA

πŸ“Œ Maps to UINavigationBar.standardAppearance property in the apple docs.
πŸ”€ compactAppearance?

βš›οΈ NavBarAppearance
TBA

πŸ“Œ Maps to UINavigationBar.compactAppearance property in the apple docs.
πŸ”€ scrollEdgeAppearance?

βš›οΈ NavBarAppearance
TBA

πŸ“Œ Maps to UINavigationBar.scrollEdgeAppearance property in the apple docs.
πŸ”€ compactScrollEdgeAppearance?

βš›οΈ NavBarAppearance
TBA

πŸ“ Note: Requires iOS 15+.

πŸ“Œ Maps to UINavigationBar.compactScrollEdgeAppearance property in the apple docs.

Object Type: NavBarAppearance

TBA

Name and Type Description
πŸ”€ baseConfig?

βš›οΈ NavBarAppearanceBaseConfig, i.e. 'defaultBackground' Β¦ 'opaqueBackground Β¦ 'transparentBackground'
TBA

πŸ“Œ Maps to either UINavigationBarAppearance.configureWithDefaultBackground, UINavigationBarAppearance.configureWithOpaqueBackground, or UINavigationBarAppearance.configureWithTransparentBackground method in the apple docs.
πŸ”€ backgroundEffect?

βš›οΈ BlurEffectStyle
TBA

πŸ“Œ Maps to UIBarAppearance.backgroundEffect property in the apple docs.
πŸ”€ backgroundColor?

βš›οΈ string Β¦ DynamicColor
TBA

πŸ“Œ Maps to UIBarAppearance.backgroundColor property in the apple docs.
πŸ”€ backgroundImage?

βš›οΈ ImageItemConfig
TBA

πŸ“Œ Maps to UIBarAppearance.backgroundImage property in the apple docs.
πŸ”€ backgroundImageContentMode?

βš›οΈ ViewContentMode
TBA

πŸ“Œ Maps to UIBarAppearance.backgroundImageContentMode property in the apple docs.
πŸ”€ shadowColor?

βš›οΈ string Β¦ DynamicColor
TBA

πŸ“Œ Maps to UIBarAppearance.shadowColor property in the apple docs.
πŸ”€ shadowImage?

βš›οΈ ImageItemConfig
TBA

πŸ“Œ Maps to UIBarAppearance.shadowImage property in the apple docs.
πŸ”€ titleTextAttributes?

βš›οΈ TextStyle
TBA

πŸ“Œ Maps to UINavigationBarAppearance.titleTextAttributes property in the apple docs.
πŸ”€ largeTitleTextAttributes?

βš›οΈ TextStyle
TBA

πŸ“Œ Maps to UINavigationBarAppearance.largeTitleTextAttributes property in the apple docs.
πŸ”€ titlePositionAdjustment?

βš›οΈ Offset
TBA

πŸ“Œ Maps to UINavigationBarAppearance.titlePositionAdjustment property in the apple docs.
πŸ”€ backIndicatorImage?

βš›οΈ ImageItemConfig
TBA

πŸ“Œ Maps to UINavigationBarAppearance.setBackIndicatorImage method in the apple docs.
πŸ”€ buttonAppearance?

βš›οΈ BarButtonItemAppearance
TBA

πŸ“Œ Maps to UINavigationBarAppearance.buttonAppearance property in the apple docs.
πŸ”€ backButtonAppearance?

βš›οΈ BarButtonItemAppearance
TBA

πŸ“Œ Maps to UINavigationBarAppearance.backButtonAppearance property in the apple docs.
πŸ”€ doneButtonAppearance?

βš›οΈ BarButtonItemAppearance
TBA

πŸ“Œ Maps to UINavigationBarAppearance.doneButtonAppearance property in the apple docs.

Enum: BarButtonItemAppearance

TBA

Name and Type Description
πŸ”€ Required: style

βš›οΈ BarButtonItemStyles i.e. plain Β¦ done
TBA

πŸ“Œ Maps to UIBarButtonItem.Style enum in the apple docs.
πŸ”€ normal?

βš›οΈ BarButtonItemStateAppearance
TBA

πŸ“Œ Maps to UIBarButtonItemAppearance.normal property in the apple docs.
πŸ”€ disabled?

βš›οΈ BarButtonItemStateAppearance
TBA

πŸ“Œ Maps to UIBarButtonItemAppearance.disabled property in the apple docs.
πŸ”€ highlighted?

βš›οΈ BarButtonItemStateAppearance
TBA

πŸ“Œ Maps to UIBarButtonItemAppearance.highlighted property in the apple docs.
πŸ”€ focused?

βš›οΈ BarButtonItemStateAppearance
TBA

πŸ“Œ Maps to UIBarButtonItemAppearance.focused property in the apple docs.

πŸ“„ 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.

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'TEXT' Β¦ 'SYSTEM_ITEM' Β¦ 'FIXED_SPACE' Β¦ 'FLEXIBLE_SPACE' Β¦ IMAGE_ASSET' Β¦ 'IMAGE_SYSTEM' Β¦ 'IMAGE_EMPTY'
Configures the type of navigation bar item to create.

Also supports creating navigation bar items based on ImageItemConfig (i.e. the string types prefixed with IMAGE, e.g. IMAGE_ASSET, etc).

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'TEXT'
TBA

πŸ“Œ Maps to UIBarButtonItem.init(title:style:target:action:) constructor in the apple docs.
πŸ”€ Required: title

βš›οΈ string
TBA

πŸ“Œ Maps to UIBarItem.title property in the apple docs.

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'SYSTEM_ITEM'
TBA

πŸ“Œ Maps to UIBarButtonItem.init(barButtonSystemItem:target:action:) constructor in the apple docs.
πŸ”€ systemItem

βš›οΈ BarButtonItemSystemItem
TBA

πŸ“Œ Maps to UIBarButtonItem.SystemItem enum in the apple docs.

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'FIXED_SPACE'
TBA

πŸ“Œ Maps to UIBarButtonItem.fixedSpace(_:) class method in the apple docs.
πŸ”€ Required: width

βš›οΈ number
TBA

πŸ“ Note: Requires iOS 14 and above

πŸ“Œ Maps to the width parameter in the UIBarButtonItem.fixedSpace(_:) class method in the apple docs.

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'FLEXIBLE_SPACE'
TBA

πŸ“ Note: Requires iOS 14 and above.

πŸ“Œ Maps to UIBarButtonItem.flexibleSpace() class method in the apple docs.

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'IMAGE_ASSET'
TBA
Supports all the properties from a ImageItemConfig with:
{ type: 'IMAGE_ASSET' }

βš›οΈ Extract<ImageItemConfig, { type: 'IMAGE_ASSET' }>
πŸ“Œ Jump to the ImageItemConfig section for more details.

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'IMAGE_SYSTEM'
TBA
Supports all the properties from a ImageItemConfig with:
{ type: 'IMAGE_SYSTEM' }

βš›οΈ Extract<ImageItemConfig, { type: 'IMAGE_SYSTEM' }>
πŸ“Œ Jump to the ImageItemConfig section for more details.

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'IMAGE_EMPTY'
TBA
Supports all the properties from a ImageItemConfig with:
{ type: 'IMAGE_EMPTY' }

βš›οΈ Extract<ImageItemConfig, { type: 'IMAGE_EMPTY' }>
πŸ“Œ Jump to the ImageItemConfig section for more details.

Object Type: NavBarItemConfigShared

TBA

Name and Type Description
πŸ”€ key?

βš›οΈ string
TBA
πŸ”€ tintColor?

βš›οΈ string Β¦ DynamicColor
TBA

πŸ“Œ Maps to UIBarButtonItem.tintColor property in the apple docs.
πŸ”€ barButtonItemStyle?

βš›οΈ BarButtonItemStyle
TBA

πŸ“Œ Maps to UIBarButtonItem.style property in the apple docs.
πŸ”€ possibleTitles?

βš›οΈ Array<string>
TBA

πŸ“Œ Maps to UIBarButtonItem.possibleTitles property in the apple docs.
πŸ”€ width?

βš›οΈ number
TBA

πŸ“Œ Maps to UIBarButtonItem.width property in the apple docs.

Object Type: NavBarItemConfigCustom

TBA

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. CUSTOM
TBA

Object Type: NavBarItemBackgroundImageConfig

TBA

Name and Type Description
πŸ”€ Required: imageItem

βš›οΈ ImageItemConfig
TBA

πŸ“Œ Maps to the backgroundImage parameter in the UIBarButtonItem.setBackgroundImage command in the apple docs.
πŸ”€ Required: controlState

βš›οΈ ControlState
TBA

πŸ“Œ Maps to the state parameter in the UIBarButtonItem.setBackgroundImage command in the apple docs.
πŸ”€ barButtonItemStyle?

βš›οΈ BarButtonItemStyle
TBA

πŸ“Œ Maps to the barMetrics parameter in the UIBarButtonItem.setBackgroundImage command in the apple docs.

Object Type: NavBarItemConfig

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

Name and Type Description
🀝 Extends NavBarItemConfigBase Shares the same properties from NavBarItemConfigBase type.
🀝 Extends NavBarItemConfigShared Shares the same properties from NavBarItemConfigShared type.
πŸ”€ backgroundImage?

βš›οΈ { [key in BarMetrics]?: NavBarItemBackgroundImageConfig }

πŸ“Œ BarMetrics
πŸ“Œ NavBarItemBackgroundImageConfig
TBA

πŸ“Œ Maps to UIBarButtonItem.setBackButtonBackgroundImage(_:for:barMetrics:) method in the apple docs.
πŸ”€ titlePositionAdjustment?

βš›οΈ { [key in BarMetrics]?: Offset }

πŸ“Œ BarMetrics
πŸ“Œ Offset
TBA

πŸ“Œ Maps to UIBarButtonItem.setBackgroundVerticalPositionAdjustment(_:for:) method in the apple docs.

Object Type: NavBarBackItemConfig

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

Name and Type Description
🀝 Extends NavBarItemConfigBase Shares the same properties from NavBarItemConfigBase type.
🀝 Extends NavBarItemConfigShared Shares the same properties from NavBarItemConfigShared type.

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

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.

Name and Type Description
πŸ”€ Required: headerMode

βš›οΈ string, ie. `'fixed'
'resize'`

Name and Type Description
πŸ”€ Required: headerMode

βš›οΈ string i.e. fixed
TBA
πŸ”€ headerHeight?

βš›οΈ HeaderHeightConfig
TBA

Name and Type Description
πŸ”€ Required: headerMode

βš›οΈ string i.e. resize
TBA
πŸ”€ headerHeightMin?

βš›οΈ HeaderHeightConfig
TBA
πŸ”€ headerHeightMax?

βš›οΈ HeaderHeightConfig
TBA

Object Type: HeaderHeightConfig

TBA

Name and Type Description
πŸ”€ Required: preset

βš›οΈ HeaderHeightPreset
TBA
πŸ”€ offset?

βš›οΈ number
TBA

Union String Type: HeaderHeightPreset

TBA

Name and Type Description
βš›οΈ navigationBar TBA
βš›οΈ statusBar TBA
βš›οΈ navigationBarWithStatusBar TBA
βš›οΈ safeArea TBA
βš›οΈ none TBA

πŸ“„ RouteSearchControllerConfig

Object Type: RouteSearchControllerConfig

TBA

Name and Type Description
πŸ”€ hidesSearchBarWhenScrolling?

βš›οΈ boolean
TBA

πŸ“Œ Maps to UINavigationItem.hidesSearchBarWhenScrolling property in the apple docs.
πŸ”€ obscuresBackgroundDuringPresentation?

βš›οΈ boolean
TBA

πŸ“Œ Maps to UISearchController.obscuresBackgroundDuringPresentation property in the apple docs.
πŸ”€ hidesNavigationBarDuringPresentation?

βš›οΈ boolean
TBA

πŸ“Œ Maps to UISearchController.hidesNavigationBarDuringPresentation property in the apple docs.
πŸ”€ automaticallyShowsCancelButton?

βš›οΈ boolean
TBA

πŸ“Œ Maps to UISearchController.automaticallyShowsCancelButton property in the apple docs.
πŸ”€ placeholder?

βš›οΈ string
TBA

πŸ“Œ Maps to UISearchBar.placeholder property in the apple docs.
πŸ”€ barTintColor?

βš›οΈ string Β¦ DynamicColor
TBA

πŸ“Œ Maps to UISearchBar.barTintColor property in the apple docs.
πŸ”€ searchBarStyle?

βš›οΈ UISearchBarStyle
TBA

πŸ“Œ Maps to UISearchBar.searchBarStyle property, and UISearchBar.Style enum in the apple docs.
πŸ”€ tintColor?

βš›οΈ string Β¦ DynamicColor
TBA

πŸ“Œ Maps to UISearchBar.tintColor property in the apple docs.
πŸ”€ isTranslucent?

βš›οΈ boolean
TBA

πŸ“Œ Maps to UISearchBar.isTranslucent property in the apple docs.
πŸ”€ textColor?

βš›οΈ string Β¦ DynamicColor
TBA
πŸ”€ returnKeyType?

βš›οΈ ReturnKeyType
TBA

πŸ“Œ Maps to UITextInputTraits.returnKeyType property in the apple docs.
πŸ”€ searchTextFieldBackgroundColor?

βš›οΈ string Β¦ DynamicColor
TBA

πŸ“ Note: On iOS 13+, this gets applied via the UISearchBar.searchTextField property, otherwise on iOS 12 and below, it's applied via directly manipulating the UITextField subview as a fallback.
πŸ”€ leftIconTintColor

βš›οΈ string Β¦ DynamicColor
TBA
πŸ”€ placeholderTextColor

βš›οΈ string Β¦ DynamicColor
TBA

Union String Type: NativeRouteData

TBA

Name and Type Description
βš›οΈ default TBA
βš›οΈ prominent TBA
βš›οΈ minimal TBA

Object Interface: RouteContentProps

TBA

Name and Type Description
πŸ”€ navigation?

βš›οΈ NavigationObject
TBA

Object Type: RouteConstantsObject

TBA

Name and Type Description
πŸ”€ isCurrentlyInFocus

βš›οΈ boolean
TBA
πŸ”€ navBarHeight

βš›οΈ number
TBA
πŸ”€ statusBarHeight

βš›οΈ number
TBA
πŸ”€ navBarWithStatusBarHeight

βš›οΈ number
TBA
πŸ”€ safeAreaInsets

βš›οΈ EdgeInsets
TBA
πŸ”€ bounds

βš›οΈ Rect
TBA

Object Type: NavigatorConstantsObject

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.

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'viewController' Β¦ 'reactRoute' Β¦ 'nativeRoute'
TBA

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'viewController'
TBA

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'reactRoute Β¦ nativeRoute'
TBA
πŸ”€ routeID

βš›οΈ number
TBA
πŸ”€ routeKey

βš›οΈ string
TBA
πŸ”€ routeIndex

βš›οΈ number
TBA

Object Type: NavigatorConstantsObject

TBA

Name and Type Description
πŸ”€ navigatorID

βš›οΈ number
TBA
πŸ”€ navBarHeight

βš›οΈ number
TBA
πŸ”€ statusBarHeight

βš›οΈ number
TBA
πŸ”€ safeAreaInsets

βš›οΈ EdgeInsets
TBA
πŸ”€ bounds

βš›οΈ Rect
TBA
πŸ”€ isPresentingModal

βš›οΈ boolean
TBA
πŸ”€ activeRoutes

βš›οΈ Array<NativeRouteData>

πŸ“Œ NativeRouteData
TBA
πŸ”€ topViewController?

βš›οΈ NativeRouteData
TBA
πŸ”€ visibleViewController?

βš›οΈ NativeRouteData
TBA

πŸ“„ RouteSearchControllerState.ts

Object Type: SearchBarState

TBA

Name and Type Description
πŸ”€ text

βš›οΈ string
TBA

πŸ“Œ Maps to UISearchBar.text property in the apple docs.
πŸ”€ showsBookmarkButton

βš›οΈ boolean
TBA

πŸ“Œ Maps to UISearchBar.showsBookmarkButton property in the apple docs.
πŸ”€ showsCancelButton

βš›οΈ boolean
TBA

πŸ“Œ Maps to UISearchBar.showsCancelButton property in the apple docs.
πŸ”€ showsSearchResultsButton

βš›οΈ boolean
TBA

πŸ“Œ Maps to UISearchBar.showsSearchResultsButton property in the apple docs.
πŸ”€ showsScopeBar

βš›οΈ boolean
TBA

πŸ“Œ Maps to UISearchBar.showsScopeBar property in the apple docs.
πŸ”€ selectedScopeButtonIndex

βš›οΈ number
TBA

πŸ“Œ Maps to UISearchBar.selectedScopeButtonIndex property in the apple docs.
πŸ”€ isSearchResultsButtonSelected

βš›οΈ boolean
TBA

πŸ“Œ Maps to UISearchBar.isSearchResultsButtonSelected property in the apple docs.

Object Type: SearchControllerState

TBA

Name and Type Description
πŸ”€ isActive

βš›οΈ boolean
TBA

πŸ“Œ Maps to UISearchController.isActive property in the apple docs.

Object Type: RouteSearchControllerState

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


πŸ“„ 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.

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'IMAGE_ASSET' Β¦ 'IMAGE_SYSTEM' Β¦ 'IMAGE_REQUIRE' Β¦ 'IMAGE_EMPTY' Β¦ 'IMAGE_RECT' Β¦ 'IMAGE_GRADIENT'
TBA

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'IMAGE_ASSET'
TBA

πŸ“Œ Maps to UIImage.init(named:) constructor in the apple docs.
πŸ”€ Required: imageValue

βš›οΈ string
TBA
πŸ”€ imageOptions?

βš›οΈ UIImageConfig
TBA

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'IMAGE_SYSTEM'
TBA

πŸ“Œ Maps to UIImage.init(systemName:withConfiguration:) constructor in the apple docs.
πŸ”€ Required: imageValue

βš›οΈ ImageSystemConfig
TBA

πŸ“Œ Maps to the withConfiguration argument label in the UIImage.init(systemName:withConfiguration:) constructor in the apple docs.
πŸ”€ imageOptions?

βš›οΈ UIImageConfig
TBA

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'IMAGE_EMPTY'
TBA

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'IMAGE_RECT'
TBA

πŸ“ Note: Programmatically creates an image using UIGraphicsImageRenderer.
πŸ”€ Required: imageValue

βš›οΈ ImageRectConfig
TBA

Name and Type Description
πŸ”€ Required: type

βš›οΈ string i.e. 'IMAGE_GRADIENT'
TBA

πŸ“ Note: Programmatically creates an image using UIGraphicsImageRenderer.
πŸ”€ imageValue

βš›οΈ ImageGradientConfig
TBA

Object Type: ImageResolvedAssetSource

TBA

Name and Type Description
πŸ”€ height

βš›οΈ number
TBA
πŸ”€ width

βš›οΈ number
TBA
πŸ”€ scale

βš›οΈ number
TBA
πŸ”€ uri

βš›οΈ string
TBA

Object Type: ImageRectConfig

TBA

Name and Type Description
πŸ”€ Required: width

βš›οΈ number
TBA
πŸ”€ Required: height

βš›οΈ number
TBA
πŸ”€ Required: fillColor

βš›οΈ string
TBA
πŸ”€ borderRadius?

βš›οΈ number
TBA

Object Type: ImageGradientConfig

TBA

Name and Type Description
πŸ”€ Required: width

βš›οΈ number
TBA
πŸ”€ Required: height

βš›οΈ number
TBA
πŸ”€ borderRadius?

βš›οΈ number
TBA
πŸ”€ Required: colors

βš›οΈ Array<string>
TBA

πŸ“Œ Maps to CAGradientLayer.colors property in the apple docs.
πŸ”€ locations?

βš›οΈ Array<number>
TBA

πŸ“Œ Maps to CAGradientLayer.locations property in the apple docs.
πŸ”€ startPoint?

βš›οΈ Point Β¦ PointPreset

πŸ“Œ Point
πŸ“Œ PointPreset
TBA

πŸ“Œ Maps to CAGradientLayer.startPoint property in the apple docs.
πŸ”€ endPoint?

βš›οΈ Point Β¦ PointPreset
πŸ“Œ Point
πŸ“Œ PointPreset
TBA

πŸ“Œ Maps to CAGradientLayer.endPoint property in the apple docs.
πŸ”€ type?

βš›οΈ string i.e. 'axial' Β¦ 'conic' Β¦ 'radial'
TBA

πŸ“Œ Maps to CAGradientLayer.type property in the apple docs.

Object Type: ImageSystemConfig

TBA

Name and Type Description
πŸ”€ Required: systemName

βš›οΈ string
TBA

πŸ“Œ Maps to the systemName argument label in the UIImage.init(systemName:withConfiguration:) constructor in the apple docs.
πŸ”€ pointSize?

βš›οΈ number
TBA

πŸ“Œ Maps to UIImage.SymbolConfiguration.init(pointSize:) constructor in the apple docs.
πŸ”€ weight?

βš›οΈ ImageSymbolWeight
TBA

πŸ“Œ Maps to UIImage.SymbolConfiguration.init(weight:) constructor in the apple docs.
πŸ”€ scale?

βš›οΈ ImageSymbolScale
TBA

πŸ“Œ Maps to UIImage.SymbolConfiguration.init(scale:) constructor in the apple docs.
πŸ”€ hierarchicalColor?

βš›οΈ Array<string>
TBA

πŸ“ Note A: Cannot be used at the same time with paletteColors (it's either one or the other).

πŸ“ Note B: Requires iOS 15+.

πŸ“Œ Maps to UIImage.SymbolConfiguration.init(hierarchicalColor:) constructor in the apple docs.
πŸ”€ paletteColors?

βš›οΈ string
TBA

πŸ“ Note A: Cannot be used at the same time with hierarchicalColor (it's either one or the other).

πŸ“ Note B: Requires iOS 15+.

πŸ“Œ Maps to UIImage.SymbolConfiguration.init(paletteColors:) constructor in the apple docs.

Enum: NavigatorErrorCodes

TBA

Name and Type Description
βš›οΈ activeRoutesDeSync TBA
βš›οΈ libraryError TBA
βš›οΈ invalidRouteID TBA
βš›οΈ invalidRouteKey TBA
βš›οΈ invalidRouteIndex TBA
βš›οΈ invalidReactTag TBA
βš›οΈ invalidArguments TBA
βš›οΈ routeOutOfBounds TBA
βš›οΈ invalidProps TBA

Object Constant: NavBarAppearancePresets

TBA

Name and Type Description
βš›οΈ hidden TBA

Undocumented Types

TBA

Type Description
πŸ“Œ Declaration: RNINavigatorRouteView.ts This file contains all the route-related events and event objects (e.g. push, pop, blur, focus, search, etc).
πŸ“Œ Declaration: RNINavigatorViewEvents.ts This file contains all the events and event objects related to the NavigatorView component. Most of these events are not exposed because they're meant for internal use only.
πŸ“Œ Declaration: MiscTypes.ts This file contains a bunch of types that haven't been categorized yet.

Contains: PointPreset, Point, DynamicColor, Offset, BlurEffectStyle, EdgeInsets, Rect, ReturnKeyType, etc.
πŸ“Œ Declaration: NavigationCommands.ts This file contains types related to the NavigationView component's navigation commands.

Contains: RouteTransitionTypes, RouteTransitionTypesEnum, RouteTransitionConfig, NavCommandPushOptions, NavCommandPopOptions, etc.

D.6. Native-Related

Native/Swift Integration


RNINavigatorManager

RNINavigatorNativeCommands

RNINavigatorManagerDelegate

RNINavigatorRouteBaseViewController

RNINavigationControllerConfig


D.7. Articles + Discussions

Discussion: RouteOptions Precedence

Every route has a corresponding "route options" configuration, and there are multiple ways to provide a "route options" configuration for a given route. At the end, all of the various "route options" are combined together as a single object, and is then applied to the route.

This means that a given "route options" configuration can be overridden by another configuration. The table below will list the order of precedence in which the routeOptions gets applied (ordered by increasing priority).

Set Route Options Via: Description
1️⃣ NavigatorView.routes prop (i.e. via the NavRouteConfigItem.routeOptionsDefault property). Default route options provided from the navigator route config (the lowest priority).
2️⃣ NavigatorView.initialRoutes prop (i.e. via the NavRouteItem.routeOptions property). The initial route options can be set via the initialRoutes prop.
3️⃣ routeOptions provided via a navigation command, e.g. navigation.push({..., routeOptions: {...}}). Some of the navigation commands lets you specify the route options for the route (e.g. push, replaceRoute, insertRoute, setRoutes, etc).
4️⃣ RouteViewPortal.routeOptions prop. The route options can also be dynamically overridden and changed via the RouteViewPortal component.
5️⃣ NavigationObject.setRouteOptions navigation command (e.g. props.navigation.setRouteOptions property). The route options can be overridden via the setRouteOptions command from the route's navigation object (the highest priority).

πŸ“ Note: Some of the commands in the "misc. convenience navigation commands" section (e.g. setRouteOptionsForRoute, setRouteOptionsForCurrentRoute, setRouteOptionsForPreviousRoute, etc) uses the NavigationObject.setRouteOptions command to apply the route options, as such by extension, it will also override all of the previous route options provided.

Discussion: RouteProps Precedence

TBA


Discussion: Customizing The Navigation Bar's Back Button

TBA





E. Getting Started Guide

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.
      //
      // The object that is passed to this prop is referred to as the
      // "route map" (i.e. `NavRoutesConfigMap`).
      //
      // The "route map" object defines what route to show for a given
      // "route key".
      // 
      // The object that's assigned to the "route key" is referred to
      // as the "route config" (i.e. `NavRouteConfigItem`).
      //
      // In other words, each "route key" in the "route map" has a 
      // corresponding "route config" that defines what route to show.
      routes={{
        // This route has a "route key" value of `routeA`.
        routeA: {
          // 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.
      //
      // In this case we want to show `routeA` first.
      initialRoutes={[{routeKey: 'routeA'}]}
    />
  );
};

GettingStartedGuide-ExampleA01


Routes and Route Config

The "route config", as the name would suggest, is an object that is used to configure a route. 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.

Via the route config object, a route can also be customized and configured further via the NavRouteConfigItem.defaultRouteOptions property (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/>
          ),
        }
      }}
    />
  );
};

GettingStartedGuide-ExampleA02


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'
        }
      }]}
    />
  );
};

GettingStartedGuide-ExampleA03


Navigation Commands Basics

The NavigationObject

The "navigation object" contains:
A. Information about the current route (e.g. routeKey, routeOptions, etc).,
B. Commands to control the navigator (e.g. pushing and popping routes, etc).,
C. Commands to configure the current route (e.g. setRouteOptions, 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 using 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>
  );
};
  

Pushing Routes

Via the navigation object, you can send commands to the navigator. In other words, you can control the navigator via the navigation object.

For example, you can push a new 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'
});

Forwarding Data To Routes (Via push)

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).

In other words, the "route props" allows you to transfer information to the next route. In the example below a counter is displayed. The count value is then incremented whenever a new route is pushed into the navigation stack. As such, for each time a new route that is pushed into the stack, the counter increments by 1.


πŸ”— 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>
  );
};

GettingStartedGuide-ExampleB03


Configuring The Next Routes (Via push)

Setting the "route options" of a route allows you to customize its appearance and behavior. As discussed in the earlier sections, when creating the configuration of a route in the NavigatorView.routes prop, you can optionally provide a RouteOptions configuration object via the NavRouteConfigItemJS.defaultRouteOptions property.

But there are other ways to provide a route with a RouteOptions config. For example, some of the navigation commands lets you set the route's route options. One such navigation command is push.

The route options that you provide via the push command will be combined with that route's initial route options (i.e. the route options that were provided via the route config: NavRouteConfigItemJS.defaultRouteOptions).

In the example below, we set the new route's routeTitle and also provide a prompt message to display in the navigation bar.


πŸ”— 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>
  );
};

GettingStartedGuide-ExampleA03


Configuring The Previous Route

TBA


Popping Routes

The current route can be popped by tapping the back button in the navigation bar. 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>
  );
};

GettingStartedGuide-ExampleA03


Navigation Command Extra Options (push and pop)

Some of the navigation command accepts extra options. For example, the extra options for push and pop navigation command allows you to enable/disable the transition animation, or provide a custom transition config, etc.

In the example below, we provide a transition config for the push and pop command so that the route has a different enter and exit transition.


πŸ”— 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>
  );
};

GettingStartedGuide-ExampleA03


Customizations Basics

Navigator Customization

One of the ways a route's navigation bar can be customized is via setting the navigator's NavigatorView.navBarAppearance prop.

Navigator-level customizations (i.e. customizations applied via the NavigatorView.navBarAppearance prop) are applied directly to the navigator instance itself, as such, it will become the default appearance for every route pushed into the navigation stack.

In the example below, the navigation bar is configured to have red background color with a red shadow and white title.


πŸ”— 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',
            },
          },
        },
      }}
    />
  );
};

GettingStartedGuide-ExampleC01


Per-Route Customization

Dynamic Customizations

Dynamic Customizations β€” Via setRouteOptions
Dynamic Customizations β€” Via RouteViewPortal

Navigation Bar Items: Adding Buttons To The Navigation Bar




F. Usage and Examples

General Navigation Bar Customization

Navigation Bar: Appearance/Legacy API

Navigation Bar β€” Legacy Customizations
Navigation Bar β€” Appearance Customizations
Applying The Navigation Bar Customizations (routeOptions)

Navigation Bar: Custom Bar Items

Navigation Bar: Adding A Search Bar

Navigation Bar: Extra Navigation Bar Height (RouteHeaderView)

Navigation Bar: Expandable Headers (RouteHeaderView)

Navigation Bar: Customizing The Back Button

Hiding The Navigation Bar


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


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

Native Integration

Creating Native Routes

Route Customizations

Pushing Routes From Native-Side

Using Native Routes From React-Side

Getting The RNINavigatorView Instance




G. Showcase, Tests and Demos

All the gifs/screenshots shown here are captured from the example app in the example directory. For convenience, each item listed in this section is its own separate route in the example app.

If you want to run the example app by yourself, please head on over to the Run Example App section for instructions.


HomeRoute


  • Contains a lists of all the showcase, tests and demo-related routes.
  • Demos the navigation bar search (i.e. RouteOptions.searchBarConfig).

HomeRoute


NavigatorShowcase01

NavigatorShowcase01


NavigatorShowcase02

NavigatorShowcase02


NavigatorShowcase03

NavigatorShowcase02


NavigatorDemo01

NavigatorShowcase02


NavigatorDemo02

NavigatorShowcase02


NavigatorTest01


  • RouteOptions.routeTitle
    • Update the navigation bar title text.
  • RouteOptions.prompt
    • Update the navigation bar prompt.
    • When set, the navigation bar height doubles and a subtitle appears above the navigation bar title.
  • RouteOptions.titleDisplayMode
    • Toggles whether or not to use large title for the current route.

NavigatorTest01


  • RouteOptions.navBarButtonLeftItemsConfig
    • Cycle through all the different ways a NavBarItemConfig can be configured (e.g. TEXT, SYSTEM_ITEM, etc).
    • Demo showing multiple navigation bar items, and then pressing them.
    • Demo showing the different ways a TEXT navigation bar item can be configured (e.g. an item with custom background images created via ImageItemConfig).
    • Shows using a react component as the custom navigation bar left item via type: 'CUSTOM'.

NavigatorTest01


  • RouteOptions.navBarButtonRightItemsConfig
    • Same as RouteOptions.navBarButtonLeftItemsConfig.

NavigatorTest01


  • RouteOptions.navBarButtonBackItemConfig

    • Cycle through all the example NavBarBackItemConfig configurations. Shows all the ways the back button can be customized.
  • RouteOptions.leftItemsSupplementBackButton

    • Toggles whether or not to show the back button when there are RouteOptions.navBarButtonLeftItemsConfig.
  • RouteOptions.applyBackButtonConfigToCurrentRoute

    • By default, the back button config is applied to next route. This toggles whether or not the back button config is applied to the current route.

    • If set to false, then the "back button"-related configs are applied to the next route.

  • RouteOptions.hidesBackButton: Toggle back button visibility.

  • RouteOptions.backButtonTitle: Change the back button text.

NavigatorTest01


NavigatorTest01


  • RouteViewPortal.renderNavBarTitleItem
    • Toggles whether or not to use a custom react component as the navigation bar's title.

NavigatorTest01


  • RouteOptions.navBarAppearanceOverride: Cycle through all the example NavBarAppearanceCombinedConfig configurations.
    • Shows all the possible ways the navigation bar can be customized.
    • Left Gif: "legacy" mode
    • Right Gif: "appearance" mode

NavigatorTest01


NavigatorTest01


  • RouteOptions.navigationBarVisibility:
    • Left: Toggle the navigation bar visibility
    • Right: Push route with its navigation bar visibility hidden.

NavigatorTest01


  • RouteOptions.statusBarStyle:
    • Left: Change the current route's StatusBarStyle.
    • Right: Push a route with StatusBarStyle.lightContent.
    • Also shows what the statusBarStyle looks likes in dark mode (i.e. "dark appearance").

NavigatorTest01


  • Left: NavigationObject.getRouteConstants()
  • Middle/Right: NavigationObject.getNavigatorConstants()

NavigatorTest01


NavigatorTest03


  • This route is used to test out the different navigation commands.
    • Each button represents a navigation command.
    • Some of the commands include pushing/popping "react" and "native" routes, adding/removing routes, manipulating the navigation stack, etc.

NavigatorTest01


NavigatorTest04


  • This route is used to test the out the built-in push and pop transitions.
    • Tests if the temporary route transitions applied via the push/pop command options works.
    • Tests if the push/pop route transitions configs applied via RouteViewPortal.routeOptions works.
    • Tests if the custom transition duration works.

NavigatorTest01


NavigatorTest05


  • This route is used to test having multiple initial routes on the navigator's first mount.
    • Shows having react and native (i.e. UIViewController) routes as the initial route items.
  • Demos the use of native routes:
    • Pushing/popping native routes from a react route (and vice versa), and sending "route props" to the next route.
    • Pushing a plain UIViewController instance to the navigator.
    • Sending commands from a native route to the JS navigator instance.

NavigatorTest01


NavigatorTest08

  • πŸ“Œ Declaration: NavigatorTest08.tsx

  • The following is used to test out a route's navigation events (e.g. onRouteWillPush, onRouteWillFocus, etc).

    • When a route event fires from a route in the bottom navigator, It'll be added to the list of events (which is sorted from newest to oldest).
    • The bottom navigator has buttons to trigger various navigation commands (e.g. push/pop, replace/remove the previous route, remove all routes, insert route, etc).

NavigatorTest01


NavigatorTest01


NavigatorTest09

TBA




H. Meta

Run Example App

# 1. Clone the repository
git clone https://github.com/dominicstop/react-native-ios-navigator.git

# 2. Initialize project
cd react-native-ios-navigator && yarn

# 3. Run Example App
yarn example ios

For convenience 😌:

git clone https://github.com/dominicstop/react-native-ios-navigator.git && cd react-native-ios-navigator && yarn && yarn example ios



I. License

MIT