react-native-ios-navigator
A native wrapper component around UINavigationController
for react-native.
π§ β οΈ Library WIP β οΈ π§
- Currently in development...
π (See TODO.md for current progress). - The documentation is incomplete (some parts/sections are marked as TBA i.e. "to be added").
- Some of the links in the documentation are broken (i.e. the URL points to
PLACE_HOLDER_LINK
).
Quick Links
Section + Link | Description |
---|---|
|
Discussion + step by step guide (w/ accompanying gifs + screenshots) on how to use this library and its various components. Related Links: |
|
Example usage that covers the various components and functionality of this library. |
|
Just some gifs, screenshots + vibes that shows what this library can do. |
|
Documentation for all the various components, functions, types, etc. Sub-Section Links: NavigatorView ComponentRouteViewPortal ComponentRouteViewEvents ComponentRouteHeaderView Component |
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).
NavigatorIOS
Resurrecting Basically, react-native
deprecated the built-in NavigatorIOS
component starting on version 0.58
.
One thing that I liked about NavigatorIOS
is that it behaved like any regular old <View/>
component. Which is fun since you can just plop it down anywhere in your app, and it'll just "work" (this included the weird quirk of having multiple navigators
π Notes
- Modal support is handled via
react-native-ios-modal
(WIP) - Adding menu's/submenu's in the navigation bar is handled via
react-native-ios-context-menu
(WIP)
A.2. Features
- 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.
- Using routes with a
- 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
bridging-header.h
file for your project.
Additional Setup
In your project's Info.plist
file, set the "View controller-based status bar appearance" key from NO
to YES
. Toggling this property allows you to set the status bar style on a per-route basis.
Troubleshooting
The following build errors can usually be resolved by adding an empty swift file:
However, the older versions of the react-native template (e.g. 0.63
and below) hard codes the swift library search paths to use swift 5.0
(which causes the linker to mismatch the swift system libraries bundled with Xcode + iOS version). To fix this issue, just remove the following entries from the project config's library search path:
Versions
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/>
),
}
}}
/>
);
};
D. Documentation
D.1. Components
NavigatorView
Component
D.1.1. 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 |
---|---|
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 ). 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).β’ RouteOptions β’ RouteOptions Precedenceβ’ NavRouteConfigItem
|
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. |
ViewProps
|
This component also supports all the standard props from a <View/> component. |
style ViewStyle
|
The style applied to the the NavigatorView component itself.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 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,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:standardAppearance (normal height),compactAppearance (compact-height, e.g. iPhones in landscape, etc.),scrollEdgeAppearance (when the navigation bar doesn't have content behind it and is currently scrolled all the way to the top), and compactScrollEdgeAppearance (a combination of compact and scroll edge, requires iOS 15+) .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".NavBarAppearanceCombinedConfig object for the full list of properties.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 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 color to navigation bar using scrollEdgeAppearance . Set this to false if you want to keep the default behaviorscrollEdgeAppearance appearance config either globally via the NavigatorView.navBarAppearance prop, or on a per-route basis via the RouteOptions.navBarAppearanceOverride property. |
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.NavRouteConfigItem.renderNavBarLeftItem in the NavigatorView.routes prop, or via RouteViewPortal.renderNavBarLeftItem prop.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.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.NavRouteConfigItem.renderNavBarRightItem in the NavigatorView.routes prop, or via RouteViewPortal.renderNavBarRightItem prop.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.NavRouteConfigItem.renderNavBarTitleItem in the NavigatorView.routes prop, or via RouteViewPortal.renderNavBarTitleItem prop.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. 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). |
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. |
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 callpop
immediately (i.e. not waiting forpush
to complete first before callingpop
), 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.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.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).β’ getActiveRoutes to get the current state of the navigation stack.β’ β’ 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.getActiveRoutes to get the current state of the navigation stack.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. push command, the routeItem must be a route that is declared in the NavigatorView.routes prop.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.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.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. 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.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. |
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. |
RouteViewPortal
Component
D.1.2. 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).
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: NavigatorView.routes prop (i.e. NavRouteConfigItem.routeOptionsDefault ),NavigatorView.initialRoutes prop (i.e. NavRouteItem.routeOptions ), ornavigation.push({..., routeOptions: {...}}) ).navigation.setRouteOptions command.For example, you can change the navigation bar title after loading a resource, or temporarily hide the back button while loading, etc. β’ 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).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.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.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
-
π Declaration:RouteViewPortalExample01.tsx
// π Note: for the sake of brevity, some of the code is omitted...
export function RouteViewPortalExample01(){
const [index, setIndex] = React.useState(0);
return (
<SafeAreaView style={styles.routeContainer}>
<RouteViewPortal
routeOptions={{
// Change the navigation bar title text
routeTitle: `index: ${index}`,
// Disable large tile
largeTitleDisplayMode: 'never',
// Set the status bar tint to 'white'
statusBarStyle: 'lightContent',
// Customize navigation bar appearance...
navBarAppearanceOverride: {
mode: 'appearance',
useStandardAppearanceAsDefault: true,
standardAppearance: {
// Set the navigation bar tint to red
backgroundColor: Colors.RED.A700,
// Make the back button text white
backButtonAppearance: {
style: 'plain',
normal: {
titleTextAttributes: {
color: 'white',
fontSize: 16,
fontWeight: '600',
},
},
},
// Make the back button icon white
backIndicatorImage: {
type: 'IMAGE_SYSTEM',
imageValue: {
systemName: 'chevron.left',
weight: 'semibold',
},
imageOptions: {
tint: 'white',
renderingMode: 'alwaysOriginal',
},
},
}
},
}}
// Use a custom component for navigation bar title
renderNavBarTitleItem={({routeOptions}) => (
<TouchableOpacity
style={styles.buttonContainer}
onPress={() => {
// Reset the index when pressed
setIndex(0);
}}
>
<Text style={styles.buttonLabel}>
{routeOptions.routeTitle ?? 'N/A'}
</Text>
</TouchableOpacity>
)}
// Use a custom component for navigation bar right item
renderNavBarRightItem={() => (
<View style={styles.navBarLeftItemContainer}>
<TouchableOpacity
style={[styles.buttonContainer, styles.buttonRightSpace]}
onPress={() => {
// Decrement the index when pressed
setIndex(prevIndex => (prevIndex - 1));
}}
>
<Text style={styles.buttonLabel}>
{`--`}
</Text>
</TouchableOpacity>
<TouchableOpacity
style={styles.buttonContainer}
onPress={() => {
// Increment the index when pressed
setIndex(prevIndex => (prevIndex + 1));
}}
>
<Text style={styles.buttonLabel}>
{`++`}
</Text>
</TouchableOpacity>
</View>
)}
/>
<View style={styles.rootContainer}>
<Text style={styles.textTitle}>
{`Current Index: ${index}`}
</Text>
</View>
</SafeAreaView>
);
};
RouteViewEvents
Component
D.1.3. 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 parentNavigatorRouteView
component and receive the route-related events.
- This is because, like the
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 theuseNavRouteEvents
hook.
Here is a list a list of the event props that this component supports. The various route-related events are documented and explained in the NavigatorRouteViewEvents
section.
-
Push/Pop-related Events
onRouteWillPush
onRouteDidPush
onRouteWillPop
onRouteDidPop
-
Focus/Blur-related Events
onRouteWillFocus
onRouteDidFocus
onRouteWillBlur
onRouteDidBlur
-
Navigation Bar Item-related Events
onPressNavBarLeftItem
onPressNavBarRightItem
-
Search Bar-Related Events
onUpdateSearchResults
onSearchBarCancelButtonClicked
onSearchBarSearchButtonClicked
RouteViewEvents
Component Example
import { RouteViewEvents } from 'react-native-ios-navigator';
// Route to show in the navigator
function ExampleRoute(props){
return (
<SafeAreaView>
<RouteViewEvents
onRouteDidPush={({nativeEvent}) => {
console.log(`Route ${nativeEvent.routeKey} was pushed...`);
}}
/>
</SafeAreaView>
);
};
RouteHeaderView
Component
D.1.4. A common UI navigation pattern is having a large header at the very top of the screen that acts as the centerpiece for a route.
- That header will either remain at a fixed size, or expand and collapse during scrolling.
- Check out
NavigatorShowcase01
,NavigatorShowcase02
andNavigatorShowcase03
for some examples.
The navigation bar cannot be easily customized (this is especially true you're trying to change the height).
- As such, this makes things like extending the navigation bar's height to show some custom UI elements underneath the title bar very difficult.
- It's also undesirable to create a custom built solution because the built-in navigation bar has a lot of expected native behaviors/functionality that will be hard to re-create (transitions, the back button, etc).
- To workaround this, some apps (e.g. spotify's album/playlist screen, etc) will just make the navigation bar's background transparent, and then show their custom UI elements underneath it.
- Other apps (like twitter's profile screen) will simply just hide navigation bar entirely, and show their own custom view (you can also do that using this library by pushing a route with
RouteOptions.navigationBarVisibility
).
- 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
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
totrue
.
RouteHeaderView
Component Props
Prop Name and Type | Description |
---|---|
config RouteHeaderConfig
|
TBA |
headerTopPadding HeaderHeightConfig
|
TBA |
style ViewStyle
|
TBA |
D.2. Context
NavigationContext
D.2.1. TBA
Name and Type | Description |
---|---|
routeID number
|
TBA |
navigatorID number
|
TBA |
navigation NavigationObject
|
TBA |
NavigatorUIConstantsContext
D.2.2. TBA
Name and Type | Description |
---|---|
navigatorID number
|
TBA |
safeAreaInsets EdgeInsets
|
TBA |
statusBarHeight number
|
TBA |
navigatorSize Rect
|
TBA |
D.3. Hooks
useNavRouteEvents
D.3.1. TBA
useNavigation
D.3.2. TBA
useNavigatorUIConstants
D.3.2. TBA
D.4. Objects and Types
This library is written using typescript. As such, all of the objects/types mentioned in the documentation (and all of the types exported by the library) will have a corresponding type declaration. Those type declaration can usually be found in the src/types
directory. If a particular object is not documented here, please refer to those type declaration files instead.
π Object Class: TSEventEmitter
See @dominicstop/ts-event-emitter for documentation.
π NavigatorRouteViewEventEmitter.ts
-
π Declaration:NavigatorRouteViewEventEmitter,ts
NavigatorRouteViewEventEmitter
Type: 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.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.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.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.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.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.onRouteDidPop (i.e. when the current route has been popped from the navigation stack). |
NavigatorRouteViewEvents
Navigation Bar Item-related Events
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.
- As such, to differentiate which item is pressed, you can use the properties provided by
event.nativeEvent
object that you'll receive from theOnPressNavBarItemEvent
. - Some of those properties are
nativeEvent.key
(an optional user-defined string), andnativeEvent.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 OnUpdateSearchResults OnUpdateSearchResultsEventObject
|
An event that is triggered whenever the search bar's text changes. Internally, this event is triggered by the UISearchResultsUpdating.updateSearchResults method.event.nativeEvent object will contain the search bar's current text value. Use the search text value to update the list accordingly. |
onSearchBarCancelButtonClicked OnSearchBarCancelButtonClicked 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 UISearchBarDelegate.searchBarCancelButtonClicked method.RouteSearchControllerConfig.automaticallyShowsCancelButton property in the route's search config). |
onSearchBarSearchButtonClicked onSearchBarSearchButtonClicked 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 UISearchBarDelegate.searchBarSearchButtonClicked method. RouteSearchControllerConfig.returnKeyType ). |
π NavRouteConfigItem.ts
-
π Declaration:NavRouteConfigItem.ts
NavRouteConfigItem
Object Type: 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
.
NavRouteConfigItemJS
Object Type: 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.initialRouteProps will be merged and potentially overridden by the following:NavigatorView.initialRoutes prop (i.e. NavRouteItem.routeProps ).push({...routeProps: {...}}) .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.NavigatorView.initialRoutes prop (i.e. NavRouteItem.routeOptions ).push({...routeOptions: {...}}) .NavigationObject.setRouteOptions(...) command.RouteViewPortal.routeOptions prop. |
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.NavigatorView.renderNavBarLeftItem prop. This property can be overridden via the route's RouteViewPortal.renderNavBarLeftItem prop.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).onPressNavBarLeftItem event. Handle the touch event yourself (e.g. via a <Button/> -like component).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.NavigatorView.renderNavBarRightItem prop. This property can be overridden via the route's RouteViewPortal.renderNavBarRightItem prop.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).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).NavigatorView.renderNavBarTitleItem prop. This property can be overridden via the route's RouteViewPortal.renderNavBarTitleItem prop.routeTitle via the navigation object (i.e. navigation.routeOptions.routeTitle ). |
NavRouteConfigItemNative
Object Type: This type is used to create and configure a "native" route.
Name and Type | Description |
---|---|
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.initialRouteProps will be merged and potentially overridden by the following:NavigatorView.initialRoutes prop (i.e. NavRouteItem.routeProps ).push({...routeProps: {...}}) .RNINavigatorRouteBaseViewController instance) can access the "route props" via self.routeProps property. |
π RouteOptions.ts
-
π Declaration:RouteOptions.ts
RouteOptions
Object Type: The properties that are related to each other are grouped together into their own sections.
RouteOptions
: General Properties
Name and Type | Description |
---|---|
statusBarStyle? StatusBarStyle
|
TBAUIStatusBarStyle 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. |
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
|
TBAUINavigationItem.title property in the apple docs. |
prompt? string
|
TBAUINavigationItem.prompt property in the apple docs. |
largeTitleDisplayMode? LargeTitleDisplayMode
|
TBAUINavigationItem.largeTitleDisplayMode property, and the UINavigationItem.LargeTitleDisplayMode enum in the apple docs. |
searchBarConfig? RouteSearchControllerConfig
|
TBAUISearchController + UISearchBar instance in the native-side.UINavigationItem.searchController property in the apple docs. |
RouteOptions
: Navigation Bar Item Config-Related Properties
Name and Type | Description |
---|---|
navBarButtonBackItemConfig? NavBarBackItemConfig
|
TBA |
navBarButtonLeftItemsConfig? NavBarItemsConfig
|
TBAUINavigationItem.leftBarButtonItems property in the apple docs. |
navBarButtonRightItemsConfig? NavBarItemsConfig
|
TBAUINavigationItem.rightBarButtonItems property in the apple docs. |
RouteOptions
: Navigation Bar Back Item Config-Related Properties
Name and Type | Description |
---|---|
backButtonTitle? string
|
TBAUINavigationItem.backButtonTitle property in the apple docs. |
hidesBackButton? boolean
|
TBAUINavigationItem.hidesBackButton property in the apple docs. |
backButtonDisplayMode? BackButtonDisplayMode
|
TBAUINavigationItem.backButtonDisplayMode property, and UINavigationItem.BackButtonDisplayMode enum in the apple docs. |
leftItemsSupplementBackButton? boolean
|
TBAUINavigationItem.leftItemsSupplementBackButton property in the apple docs. |
applyBackButtonConfigToCurrentRoute? boolean false
|
TBA |
RouteOptions
: Override-related Properties
Name and Type | Description |
---|---|
navBarAppearanceOverride? NavBarAppearanceCombinedConfig
|
TBA |
navigationBarVisibility? NavigationBarVisibilityMode
|
TBA |
allowTouchEventsToPassThroughNavigationBar? boolean
|
TBA |
π NavigationObject.ts
-
π Declaration:NavigationObject.ts
NavigationObject
Object Type: TBA
NavigationObject
: General Properties
Name and Type | Description |
---|---|
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. |
NavigationObject
: Route Commands
Name and Type | Description |
---|---|
getRouteOptions () => RouteOptions
|
TBA |
setRouteOptions |
null) => void` |
setHidesBackButton (isHidden: boolean, animated: boolean) => void
|
TBA |
getRouteConstants () => Promise<RouteConstantsObject>
|
TBA |
NavigationObject
: "Get Ref" Commands
Name and Type | Description |
---|---|
getRefToRoute () => NavigatorRouteView
|
TBA |
getRefToNavigator () => NavigatorView
|
TBA |
getRefToNavRouteEmitter () => NavigatorRouteViewEventEmitter
|
TBA |
π NavRouteItem.ts
-
π Declaration:NavRouteItem.ts
NavRouteItem
Object Type: TBA
Name and Type | Description |
---|---|
routeKey string
|
TBA |
routeProps? object
|
TBA |
routeOptions? RouteOptions
|
TBA |
NavRouteStackItem
Object Type: Represents an active route item in the navigation stack. This type extends NavRouteItem
, as such they share the same properties.
Name and Type | Description |
---|---|
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 |
NavRouteStackPartialItem
Object Type: 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 |
---|---|
NavRouteStackItem
|
Shares the same properties from NavRouteStackItem (and NavRouteItem ). |
routeID? number
|
TBA |
π NavBarAppearanceConfig.ts
-
π Declaration:NavBarAppearanceConfig.ts
NavBarAppearanceCombinedConfig
Object Type: 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).
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 thatappearance
mode can't (and vice versa). For example, vialegacy
mode, you can set the global tint of all the navigation bar elements viatintColor
.
Example Snippet
const navBarAppearanceLegacy = {
mode: 'appearance',
// `NavBarAppearanceConfig`-related properties
// ...
};
const navBarAppearance = {
mode: 'legacy',
// `NavBarAppearanceLegacyConfig`-related properties
// ...
};
NavBarAppearanceLegacyConfig
Object Type: Name and Type | Description |
---|---|
navBarPreset? NavBarPreset e.g. 'none' Β¦ 'noShadow' Β¦ 'clearBackground' none
|
TBA |
barStyle? BarStyle e.g.'default' Β¦ 'black'
|
TBAUINavigationBar.barStyle property in the apple docs. |
titleTextAttributes? TextStyle
|
TBAUINavigationBar.titleTextAttributes property in the apple docs. |
largeTitleTextAttributes? TextStyle
|
TBAUINavigationBar.largeTitleTextAttributes property in the apple docs. |
titleVerticalPositionAdjustment? { [key in BarMetrics]?: number } BarMetrics
|
TBAUINavigationBar.setTitleVerticalPositionAdjustment method in the apple docs. |
tintColor? string Β¦ DynamicColor
|
TBAUINavigationBar.tintColor property in the apple docs. |
barTintColor? string Β¦ DynamicColor
|
TBAscrollEdgeAppearance .UINavigationBar.barTintColor property in the apple docs. |
backIndicatorImage? ImageItemConfig
|
TBAUINavigationBar.backIndicatorImage property in the apple docs. |
backgroundImage? { [key in BarMetrics]?: ImageItemConfig } BarMetrics ImageItemConfig
|
TBAUINavigationBar.setBackgroundImage method in the apple docs. |
shadowImage? ImageItemConfig
|
TBAUINavigationBar.shadowImage property in the apple docs. |
NavBarAppearanceConfig
Object Type: 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' none
|
TBA |
useStandardAppearanceAsDefault? boolean false
|
TBA |
standardAppearance? NavBarAppearance
|
TBAUINavigationBar.standardAppearance property in the apple docs. |
compactAppearance? NavBarAppearance
|
TBAUINavigationBar.compactAppearance property in the apple docs. |
scrollEdgeAppearance? NavBarAppearance
|
TBAUINavigationBar.scrollEdgeAppearance property in the apple docs. |
compactScrollEdgeAppearance? NavBarAppearance
|
TBAUINavigationBar.compactScrollEdgeAppearance property in the apple docs. |
NavBarAppearance
Object Type: TBA
Name and Type | Description |
---|---|
baseConfig? NavBarAppearanceBaseConfig , i.e. 'defaultBackground' Β¦ 'opaqueBackground Β¦ 'transparentBackground'
|
TBAUINavigationBarAppearance.configureWithDefaultBackground , UINavigationBarAppearance.configureWithOpaqueBackground , or UINavigationBarAppearance.configureWithTransparentBackground method in the apple docs. |
backgroundEffect? BlurEffectStyle
|
TBAUIBarAppearance.backgroundEffect property in the apple docs. |
backgroundColor? string Β¦ DynamicColor
|
TBAUIBarAppearance.backgroundColor property in the apple docs. |
backgroundImage? ImageItemConfig
|
TBAUIBarAppearance.backgroundImage property in the apple docs. |
backgroundImageContentMode? ViewContentMode
|
TBAUIBarAppearance.backgroundImageContentMode property in the apple docs. |
shadowColor? string Β¦ DynamicColor
|
TBAUIBarAppearance.shadowColor property in the apple docs. |
shadowImage? ImageItemConfig
|
TBAUIBarAppearance.shadowImage property in the apple docs. |
titleTextAttributes? TextStyle
|
TBAUINavigationBarAppearance.titleTextAttributes property in the apple docs. |
largeTitleTextAttributes? TextStyle
|
TBAUINavigationBarAppearance.largeTitleTextAttributes property in the apple docs. |
titlePositionAdjustment? Offset
|
TBAUINavigationBarAppearance.titlePositionAdjustment property in the apple docs. |
backIndicatorImage? ImageItemConfig
|
TBAUINavigationBarAppearance.setBackIndicatorImage method in the apple docs. |
buttonAppearance? BarButtonItemAppearance
|
TBAUINavigationBarAppearance.buttonAppearance property in the apple docs. |
backButtonAppearance? BarButtonItemAppearance
|
TBAUINavigationBarAppearance.backButtonAppearance property in the apple docs. |
doneButtonAppearance? BarButtonItemAppearance
|
TBAUINavigationBarAppearance.doneButtonAppearance property in the apple docs. |
BarButtonItemAppearance
Enum: -
π Declaration:BarButtonItemAppearance
TBA
Name and Type | Description |
---|---|
style BarButtonItemStyles i.e. plain Β¦ done
|
TBAUIBarButtonItem.Style enum in the apple docs. |
normal? BarButtonItemStateAppearance
|
TBAUIBarButtonItemAppearance.normal property in the apple docs. |
disabled? BarButtonItemStateAppearance
|
TBAUIBarButtonItemAppearance.disabled property in the apple docs. |
highlighted? BarButtonItemStateAppearance
|
TBAUIBarButtonItemAppearance.highlighted property in the apple docs. |
focused? BarButtonItemStateAppearance
|
TBAUIBarButtonItemAppearance.focused property in the apple docs. |
π NavBarItemConfig.ts
-
π Declaration:NavBarItemConfig.ts
NavBarItemConfigBase
Object Type: 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 |
---|---|
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 |
---|---|
type string i.e. 'TEXT'
|
TBAUIBarButtonItem.init(title:style:target:action:) constructor in the apple docs. |
title string
|
TBAUIBarItem.title property in the apple docs. |
Name and Type | Description |
---|---|
type string i.e. 'SYSTEM_ITEM'
|
TBAUIBarButtonItem.init(barButtonSystemItem:target:action:) constructor in the apple docs. |
systemItem BarButtonItemSystemItem
|
TBAUIBarButtonItem.SystemItem enum in the apple docs. |
Name and Type | Description |
---|---|
type string i.e. 'FIXED_SPACE'
|
TBAUIBarButtonItem.fixedSpace(_:) class method in the apple docs. |
width number
|
TBAwidth parameter in the UIBarButtonItem.fixedSpace(_:) class method in the apple docs. |
Name and Type | Description |
---|---|
type string i.e. 'FLEXIBLE_SPACE'
|
TBAUIBarButtonItem.flexibleSpace() class method in the apple docs. |
Name and Type | Description |
---|---|
type string i.e. 'IMAGE_ASSET'
|
TBA |
Supports all the properties from a ImageItemConfig with:{ type: 'IMAGE_ASSET' } Extract<ImageItemConfig, { type: 'IMAGE_ASSET' }>
|
ImageItemConfig section for more details. |
Name and Type | Description |
---|---|
type string i.e. 'IMAGE_SYSTEM'
|
TBA |
Supports all the properties from a ImageItemConfig with:{ type: 'IMAGE_SYSTEM' } Extract<ImageItemConfig, { type: 'IMAGE_SYSTEM' }>
|
ImageItemConfig section for more details. |
Name and Type | Description |
---|---|
type string i.e. 'IMAGE_EMPTY'
|
TBA |
Supports all the properties from a ImageItemConfig with:{ type: 'IMAGE_EMPTY' } Extract<ImageItemConfig, { type: 'IMAGE_EMPTY' }>
|
ImageItemConfig section for more details. |
NavBarItemConfigShared
Object Type: TBA
Name and Type | Description |
---|---|
key? string
|
TBA |
tintColor? string Β¦ DynamicColor
|
TBAUIBarButtonItem.tintColor property in the apple docs. |
barButtonItemStyle? BarButtonItemStyle
|
TBAUIBarButtonItem.style property in the apple docs. |
possibleTitles? Array<string>
|
TBAUIBarButtonItem.possibleTitles property in the apple docs. |
width? number
|
TBAUIBarButtonItem.width property in the apple docs. |
NavBarItemConfigCustom
Object Type: TBA
Name and Type | Description |
---|---|
type string i.e. CUSTOM
|
TBA |
NavBarItemBackgroundImageConfig
Object Type: TBA
Name and Type | Description |
---|---|
imageItem ImageItemConfig
|
TBAbackgroundImage parameter in the UIBarButtonItem.setBackgroundImage command in the apple docs. |
controlState ControlState
|
TBAstate parameter in the UIBarButtonItem.setBackgroundImage command in the apple docs. |
barButtonItemStyle? BarButtonItemStyle
|
TBAbarMetrics parameter in the UIBarButtonItem.setBackgroundImage command in the apple docs. |
NavBarItemConfig
Object Type: 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 |
---|---|
NavBarItemConfigBase
|
Shares the same properties from NavBarItemConfigBase type. |
NavBarItemConfigShared
|
Shares the same properties from NavBarItemConfigShared type. |
backgroundImage? { [key in BarMetrics]?: NavBarItemBackgroundImageConfig } BarMetrics NavBarItemBackgroundImageConfig
|
TBAUIBarButtonItem.setBackButtonBackgroundImage(_:for:barMetrics:) method in the apple docs. |
titlePositionAdjustment? { [key in BarMetrics]?: Offset } BarMetrics Offset
|
TBAUIBarButtonItem.setBackgroundVerticalPositionAdjustment(_:for:) method in the apple docs. |
NavBarBackItemConfig
Object Type: 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 |
---|---|
NavBarItemConfigBase
|
Shares the same properties from NavBarItemConfigBase type. |
NavBarItemConfigShared
|
Shares the same properties from NavBarItemConfigShared type. |
NavBarItemsConfig
Object Type: A union type that can either be an array of NavBarItemConfig
or a tuple containing a single element of NavBarItemConfigCustomBase
.
π RouteHeaderConfig.ts
-
π Declaration:RouteHeaderConfig.ts
RouteHeaderConfig
Object Type: 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 |
---|---|
headerMode string , ie. `'fixed' |
'resize'` |
Name and Type | Description |
---|---|
headerMode string i.e. fixed
|
TBA |
headerHeight? HeaderHeightConfig
|
TBA |
Name and Type | Description |
---|---|
headerMode string i.e. resize
|
TBA |
headerHeightMin? HeaderHeightConfig
|
TBA |
headerHeightMax? HeaderHeightConfig
|
TBA |
HeaderHeightConfig
Object Type: TBA
Name and Type | Description |
---|---|
preset HeaderHeightPreset
|
TBA |
offset? number
|
TBA |
HeaderHeightPreset
Union String Type: TBA
Name and Type | Description |
---|---|
navigationBar
|
TBA |
statusBar
|
TBA |
navigationBarWithStatusBar
|
TBA |
safeArea
|
TBA |
none
|
TBA |
HeaderHeightConfig
π RouteSearchControllerConfig
-
π Declaration:RouteSearchControllerConfig
RouteSearchControllerConfig
Object Type: TBA
Name and Type | Description |
---|---|
hidesSearchBarWhenScrolling? boolean
|
TBAUINavigationItem.hidesSearchBarWhenScrolling property in the apple docs. |
obscuresBackgroundDuringPresentation? boolean
|
TBAUISearchController.obscuresBackgroundDuringPresentation property in the apple docs. |
hidesNavigationBarDuringPresentation? boolean
|
TBAUISearchController.hidesNavigationBarDuringPresentation property in the apple docs. |
automaticallyShowsCancelButton? boolean
|
TBAUISearchController.automaticallyShowsCancelButton property in the apple docs. |
placeholder? string
|
TBAUISearchBar.placeholder property in the apple docs. |
barTintColor? string Β¦ DynamicColor
|
TBAUISearchBar.barTintColor property in the apple docs. |
searchBarStyle? UISearchBarStyle
|
TBAUISearchBar.searchBarStyle property, and UISearchBar.Style enum in the apple docs. |
tintColor? string Β¦ DynamicColor
|
TBAUISearchBar.tintColor property in the apple docs. |
isTranslucent? boolean
|
TBAUISearchBar.isTranslucent property in the apple docs. |
textColor? string Β¦ DynamicColor
|
TBA |
returnKeyType? ReturnKeyType
|
TBAUITextInputTraits.returnKeyType property in the apple docs. |
searchTextFieldBackgroundColor? string Β¦ DynamicColor
|
TBAUISearchBar.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 |
NativeRouteData
Union String Type: TBA
Name and Type | Description |
---|---|
default
|
TBA |
prominent
|
TBA |
minimal
|
TBA |
RouteContentProps
Object Interface: -
π Declaration:NavigatorRouteView
TBA
Name and Type | Description |
---|---|
navigation? NavigationObject
|
TBA |
RouteConstantsObject
Object Type: -
π Declaration:RNINavigatorRouteViewModule
TBA
Name and Type | Description |
---|---|
isCurrentlyInFocus boolean
|
TBA |
navBarHeight number
|
TBA |
statusBarHeight number
|
TBA |
navBarWithStatusBarHeight number
|
TBA |
safeAreaInsets EdgeInsets
|
TBA |
bounds Rect
|
TBA |
NavigatorConstantsObject
Object Type: -
π Declaration:RNINavigatorViewModule
NativeRouteData
Object Type: 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 |
---|---|
type string i.e. 'viewController' Β¦ 'reactRoute' Β¦ 'nativeRoute'
|
TBA |
Name and Type | Description |
---|---|
type string i.e. 'viewController'
|
TBA |
Name and Type | Description |
---|---|
type string i.e. 'reactRoute Β¦ nativeRoute'
|
TBA |
routeID number
|
TBA |
routeKey string
|
TBA |
routeIndex number
|
TBA |
NavigatorConstantsObject
Object Type: 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 |
π ImageItemConfig.ts
-
π Declaration:ImageItemConfig.ts
ImageItemConfig
Object Type: 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 |
---|---|
type string i.e. 'IMAGE_ASSET' Β¦ 'IMAGE_SYSTEM' Β¦ 'IMAGE_REQUIRE' Β¦ 'IMAGE_EMPTY' Β¦ 'IMAGE_RECT' Β¦ 'IMAGE_GRADIENT'
|
TBA |
Name and Type | Description |
---|---|
type string i.e. 'IMAGE_ASSET'
|
TBAUIImage.init(named:) constructor in the apple docs. |
imageValue string
|
TBA |
imageOptions? UIImageConfig
|
TBA |
Name and Type | Description |
---|---|
type string i.e. 'IMAGE_SYSTEM'
|
TBAUIImage.init(systemName:withConfiguration:) constructor in the apple docs. |
imageValue ImageSystemConfig
|
TBAwithConfiguration argument label in the UIImage.init(systemName:withConfiguration:) constructor in the apple docs. |
imageOptions? UIImageConfig
|
TBA |
Name and Type | Description |
---|---|
type string i.e. 'IMAGE_EMPTY'
|
TBA |
Name and Type | Description |
---|---|
type string i.e. 'IMAGE_RECT'
|
TBAUIGraphicsImageRenderer . |
imageValue ImageRectConfig
|
TBA |
Name and Type | Description |
---|---|
type string i.e. 'IMAGE_GRADIENT'
|
TBAUIGraphicsImageRenderer . |
imageValue ImageGradientConfig
|
TBA |
ImageResolvedAssetSource
Object Type: TBA
Name and Type | Description |
---|---|
height number
|
TBA |
width number
|
TBA |
scale number
|
TBA |
uri string
|
TBA |
ImageRectConfig
Object Type: TBA
Name and Type | Description |
---|---|
width number
|
TBA |
height number
|
TBA |
fillColor string
|
TBA |
borderRadius? number
|
TBA |
ImageGradientConfig
Object Type: TBA
Name and Type | Description |
---|---|
width number
|
TBA |
height number
|
TBA |
borderRadius? number
|
TBA |
colors Array<string>
|
TBACAGradientLayer.colors property in the apple docs. |
locations? Array<number>
|
TBACAGradientLayer.locations property in the apple docs. |
startPoint? Point Β¦ PointPreset Point PointPreset
|
TBACAGradientLayer.startPoint property in the apple docs. |
endPoint? Point Β¦ PointPreset Point PointPreset
|
TBACAGradientLayer.endPoint property in the apple docs. |
type? string i.e. 'axial' Β¦ 'conic' Β¦ 'radial'
|
TBACAGradientLayer.type property in the apple docs. |
ImageSystemConfig
Object Type: TBA
Name and Type | Description |
---|---|
systemName string
|
TBAsystemName argument label in the UIImage.init(systemName:withConfiguration:) constructor in the apple docs. |
pointSize? number
|
TBAUIImage.SymbolConfiguration.init(pointSize:) constructor in the apple docs. |
weight? ImageSymbolWeight
|
TBAUIImage.SymbolConfiguration.init(weight:) constructor in the apple docs. |
scale? ImageSymbolScale
|
TBAUIImage.SymbolConfiguration.init(scale:) constructor in the apple docs. |
hierarchicalColor? Array<string>
|
TBApaletteColors (it's either one or the other).UIImage.SymbolConfiguration.init(hierarchicalColor:) constructor in the apple docs. |
paletteColors? string
|
TBAhierarchicalColor (it's either one or the other).UIImage.SymbolConfiguration.init(paletteColors:) constructor in the apple docs. |
NavigatorErrorCodes
Enum: -
π Declaration:NavigatorError
TBA
Name and Type | Description |
---|---|
activeRoutesDeSync
|
TBA |
libraryError
|
TBA |
invalidRouteID
|
TBA |
invalidRouteKey
|
TBA |
invalidRouteIndex
|
TBA |
invalidReactTag
|
TBA |
invalidArguments
|
TBA |
routeOutOfBounds
|
TBA |
invalidProps
|
TBA |
NavBarAppearancePresets
Object Constant: -
π Declaration:NavBarAppearancePresets
TBA
Name and Type | Description |
---|---|
hidden
|
TBA |
Undocumented Types
TBA
Type | Description |
---|---|
RNINavigatorRouteView.ts
|
This file contains all the route-related events and event objects (e.g. push, pop, blur, focus, search, etc). |
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. |
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. |
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
RouteOptions
Precedence
Discussion: There are multiple ways to set a route's routeOptions
config, but only one of them will take effect (in other words, a route's routeOptions
can be overridden when all of the route options are being merged together). The table below will list the order of precedence in which the routeOptions
gets applied (ordered by increasing priority).
Set Route Options Via: | Description |
---|---|
NavigatorView.routes prop (i.e. NavRouteConfigItem.routeOptionsDefault property). |
Default route options provided from the navigator route config. |
NavigatorView.initialRoutes prop (i.e. NavRouteItem.routeOptions property). |
The initial route options can be set via the initialRoutes prop. |
routeOptions provided via navigation command, e.g. navigation.push({..., routeOptions: {...}}) . |
Some of the navigation commands lets you set the route options for the route (e.g. push , replaceRoute , insertRoute , setRoutes , etc). |
RouteViewPortal.routeOptions prop. |
The route options can also be dynamically overridden and changed via the RouteViewPortal . |
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. |
E. Getting Started Guide
A01 - Navigation Hello World
Here's a bare minimum example: a navigator with a single route.
import * as React from 'react';
import { SafeAreaView, TouchableOpacity, Text, StyleSheet } from 'react-native';
import { NavigatorView, RouteContentProps } from 'react-native-ios-navigator';
// Route - 'routeA'
// This is the component that gets shown when 'routeA' is pushed.
function ExampleRoute(props){
return (
<SafeAreaView style={styles.routeContainer}>
<TouchableOpacity
style={styles.button}
onPress={() => {
// when this button is pressed, push a route
// with the "route key" value of 'routeA'.
props.navigation.push({
routeKey: 'routeA'
});
}}
>
<Text style={styles.buttonText}>
Push: 'RouteA'
</Text>
</TouchableOpacity>
</SafeAreaView>
);
};
export function ExampleA01(){
return (
<NavigatorView
// The object that's passed to the `NavigatorView.routes`
// prop defines what routes can be used in the navigator.
//
// Note: The object that is passed to this prop is referred to as
// the "route map" (e.g. `NavRoutesConfigMap`).
routes={{
// The key of the property is used as the "route key" of the route.
// E.g. so this is a route that has the `routeKey` value of 'routeA'.
//
// Note: The object that's assigned to the `routeKey` is referred to
// as the "route config" (e.g. `NavRouteConfigItem`).
routeA: {
// Now we need to provide a config... we want to show the
// `ExampleRoute` component when this route is "pushed".
//
// The `renderRoute` property accepts a function that returns a
// component to show in the route.
renderRoute: () => (
<ExampleRoute/>
),
}
}}
// This prop controls the initial routes to show when the navigator
// first mounts.
initialRoutes={[{routeKey: 'routeA'}]}
/>
);
};
A02 - Routes and Route Config
The "route config", as the name would suggest, is used to configure a route. As such, each route has a corresponding "route config" object.
The route config object's renderRoute
property (e.g.NavRouteConfigItem.renderRoute
) defines what route to show when it gets pushed.
The route config object can also be customized and configured further via the defaultRouteOptions
property (e.g. e.g.NavRouteConfigItem.defaultRouteOptions
).
// π Note: for the sake of brevity, some of the code is omitted...
export function ExampleA02(){
return (
<NavigatorView
// ...
routes={{
routeA: {
// The route can be configured/customized further via the
// `NavRouteConfigItem.defaultRouteOptions` property.
routeOptionsDefault: {
routeTitle: 'Hello World',
prompt: 'Lorum Ipsum',
// disable the "large title" for this route
largeTitleDisplayMode: 'never',
// show a button on the right side of the
// navigation bar
navBarButtonRightItemsConfig: [{
type: 'TEXT',
title: 'ABC',
tintColor: 'red',
}]
},
renderRoute: () => (
<ExampleRoute/>
),
}
}}
/>
);
};
A03 - Initial Routes
As mentioned before, the NavigatorView.initialRoutes
prop controls what routes to show when the navigator first mounts.
For most cases, you only want one initial route. But you can define multiple initial routes if you want to (e.g. for the purpose of state restoration, etc).
// π Note: for the sake of brevity, some of the code is omitted...
export function ExampleA03(){
return (
<NavigatorView
// ...
//
// show multiple initial routes...
// Note: this prop accepts an array of `NavRouteItem` objects
initialRoutes={[{
routeKey: 'routeA',
routeOptions: {
routeTitle: '01 (Root)'
}
}, {
routeKey: 'routeA',
routeOptions: {
routeTitle: '02'
}
}, {
routeKey: 'routeA',
routeOptions: {
routeTitle: '03'
}
}, {
routeKey: 'routeA',
routeOptions: {
routeTitle: '04'
}
}, {
routeKey: 'routeA',
routeOptions: {
routeTitle: '05'
}
}, {
routeKey: 'routeA',
routeOptions: {
routeTitle: '06'
}
}]}
/>
);
};
Navigation Commands Basics
NavigationObject
B01 β The The "navigation object" contains information about the current route, and is also used to send commands to the navigator (e.g. pushing and popping routes, etc).
There are two ways to get the navigation object. The first way is to simply get the navigation object via the props:
// 1. your route component will automatically receive the `NavigationObject` via props.
function ExampleRoute(props){
const { navigation } = props;
return (
// ...
);
};
// 2. If you are using typescript, you can use (or extend) the `RouteContentProps` type.
import type { RouteContentProps } from 'react-native-ios-navigator';
function ExampleRoute(props: RouteContentProps){
const text = `The current route key is: ${props.navigation.routeKey}`;
return (
// ...
);
};
The second way to get the navigation object is via context:
// 1. For convenience, there's a pre-built hook to get the navigation object
// via context.
import { useNavigation } from 'react-native-ios-navigator';
function ExampleRoute(){
const navigation = useNavigation();
return (
// ...
);
};
// 2. Or altenatively, you can use the `NavigationContext` directly for more
// flexibility and control.
import { NavigationContext } from 'react-native-ios-navigator';
function ExampleRoute(){
return (
<NavigationContext.Consumer>
{(navigation) => (
// ...
)}
</NavigationContext.Consumer>
);
};
B02 β Pushing Routes
Via the navigation object, you can send commands to the navigator. For example, you can push a route into the navigation stack using the "push" command:
// The push command accepts an object...
navigation.push({
// The "route key" of the route that is to be shown
routeKey: 'routeA'
});
B03 - Forwarding Data To Routes
Using the push navigation command, you can send data (i.e. "route props") to the next route. The data can then be read via the navigation object (i.e. NavigationObject.routeProps
).
// π Note: for the sake of brevity, some of the code is omitted...
function ExampleRoute(props){
// Get the count from the prev. route.
const prevCount = props.navigation.routeProps?.count ?? 0;
// Save the count to state
const [count] = React.useState(prevCount);
return (
<SafeAreaView style={styles.routeContainer}>
<TouchableOpacity
style={styles.button}
onPress={() => {
// Push route when this button is pressed...
props.navigation.push({
routeKey: 'routeA',
routeProps: {
// ... and send the count to the next route.
count: count + 1,
},
routeOptions: {
routeTitle: `Count: ${count}`
},
});
}}
>
<Text style={styles.buttonText}>
{`Push and Increment Counter`}
</Text>
</TouchableOpacity>
</SafeAreaView>
);
};
B04 - Configure The Next Routes
The "route options" of a route can also be set via a navigation command. The "route options" provided by the navigation command will be combined with the route's pre-existing route options (i.e. the route options that were provided via the route config: NavRouteConfigItem.defaultRouteOptions
).
// π Note: for the sake of brevity, some of the code is omitted...
function ExampleRoute(props){
return (
<SafeAreaView style={styles.routeContainer}>
<TouchableOpacity
style={styles.button}
onPress={() => {
// Push route when this button is pressed...
props.navigation.push({
routeKey: 'routeA',
// ...and set the route's route options
routeOptions: {
largeTitleDisplayMode: 'never',
routeTitle: 'Hello World',
prompt: 'Lorum Ipsum',
},
});
}}
>
<Text style={styles.buttonText}>
Push: 'RouteA' + Send Route Options
</Text>
</TouchableOpacity>
</SafeAreaView>
);
};
B05 - Popping Routes
To programmatically pop the current route, you can use the pop
navigation command.
// π Note: for the sake of brevity, some of the code is omitted...
function ExampleRoute(props){
return (
<SafeAreaView style={styles.routeContainer}>
{/** ... */}
<TouchableOpacity
style={styles.button}
onPress={() => {
// Pop current route when the button is pressed
props.navigation.pop();
}}
>
<Text style={styles.buttonText}>
Pop Current Route
</Text>
</TouchableOpacity>
</SafeAreaView>
);
};
B06 - Extra Options
Most of the navigation commands can accept extra options. The extra options can be used to enable/disable the transition animation, or provide a custom transition config to use, etc.
// π Note: for the sake of brevity, some of the code is omitted...
function ExampleRoute(props){
return (
<SafeAreaView style={styles.routeContainer}>
<TouchableOpacity
style={styles.button}
onPress={() => {
// Push 'routeA' with a custom transition
props.navigation.push({
routeKey: 'routeA',
}, {
transitionConfig: {
type: 'GlideUp',
duration: 0.75
}
});
}}
>
<Text style={styles.buttonText}>
Push: 'RouteA'
</Text>
</TouchableOpacity>
<TouchableOpacity
style={styles.button}
onPress={() => {
// Pop current route w/ a custom transition
props.navigation.pop({
transitionConfig: {
type: 'FlipHorizontal',
duration: 0.75,
}
});
}}
>
<Text style={styles.buttonText}>
Pop Current Route
</Text>
</TouchableOpacity>
</SafeAreaView>
);
};
Customizations Basics
C01 - Navigator Customization
You can "globally" apply customization on the navigation bar via setting some props on the navigator itself. Navigator-level customizations are "global" in the sense that it'll be applied to all the routes that will be shown in the navigator.
// π Note: for the sake of brevity, some of the code is omitted...
export function ExampleC01(){
return (
<NavigatorView
// ...
// Customize the look of the navigation bar
navBarAppearance={{
// Use the appearance API (i.e. iOS 13 and above) to style
// the navigation bar
mode: 'appearance',
useStandardAppearanceAsDefault: true,
standardAppearance: {
// Set nav bar bg to red
backgroundColor: 'red',
// Make the nav bar title white
titleTextAttributes: {
color: 'white',
fontSize: 16,
fontWeight: 'bold',
},
// Add a gradient shadow below the nav bar
shadowImage: {
type: 'IMAGE_GRADIENT',
imageValue: {
colors: ['rgba(255,0,0,1)', 'rgba(255,0,0,0)'],
type: 'axial',
height: 75,
startPoint: 'top',
endPoint: 'bottom',
},
},
},
}}
/>
);
};
Per-Route Customization
Dynamic Customizations
Navigation Bar Items (Basic)
F. Usage and Examples
F.1. Navigation Bar Customizations
Navigation Bar: Appearance/Legacy API
Navigation Bar β Legacy Customizations
Navigation Bar β Appearance Customizations
Navigation Bar: Custom Bar Items
Navigation Bar: Search Bar
RouteHeaderView
Navigation Bar: F.2. Navigation Commands
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 Command: F.3. Navigation Events
NavigatorView
Events
Route-Level Events
NavigatorRouteViewEventEmitter
Route Events:
RouteViewEvents
Component
Route Events:
useNavRouteEvents
Hooks
Route Events: Route Lifecycle Events
Navigation Bar-Related Events
F.4. Native Integration
Creating Native Routes
Route Customizations
Pushing Routes From Native-Side
Using Native Routes From React-Side
RNINavigatorView
Instance
Getting The 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
-
π Declaration:HomeRoute.tsx
- Contains a lists of all the showcase, tests and demo-related routes.
- Demos the navigation bar search (i.e.
RouteOptions.searchBarConfig
).
NavigatorShowcase01
-
π Declaration:NavigatorShowcase01.tsx
NavigatorShowcase02
-
π Declaration:NavigatorShowcase02.tsx
NavigatorShowcase03
-
π Declaration:NavigatorShowcase03.tsx
NavigatorDemo01
-
π Declaration:NavigatorDemo01.tsx
NavigatorDemo02
-
π Declaration:NavigatorDemo02.tsx
NavigatorTest01
-
π Declaration:NavigatorTest01.tsx
-
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.
-
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 viaImageItemConfig
). - Shows using a react component as the custom navigation bar left item via
type: 'CUSTOM'
.
- Cycle through all the different ways a
-
RouteOptions.navBarButtonRightItemsConfig
- Same as
RouteOptions.navBarButtonLeftItemsConfig
.
- Same as
-
RouteOptions.navBarButtonBackItemConfig
- Cycle through all the example
NavBarBackItemConfig
configurations. Shows all the ways the back button can be customized.
- Cycle through all the example
-
RouteOptions.leftItemsSupplementBackButton
- Toggles whether or not to show the back button when there are
RouteOptions.navBarButtonLeftItemsConfig
.
- Toggles whether or not to show the back button when there are
-
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.
-
RouteViewPortal.renderNavBarTitleItem
- Toggles whether or not to use a custom react component as the navigation bar's title.
-
RouteOptions.navBarAppearanceOverride
: Cycle through all the exampleNavBarAppearanceCombinedConfig
configurations.- Shows all the possible ways the navigation bar can be customized.
- Left Gif: "legacy" mode
- Right Gif: "appearance" mode
-
RouteOptions.navigationBarVisibility
:- Left: Toggle the navigation bar visibility
- Right: Push route with its navigation bar visibility hidden.
-
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").
-
Left: Change the current route's
-
Left:
NavigationObject.getRouteConstants()
-
Middle/Right:
NavigationObject.getNavigatorConstants()
NavigatorTest03
-
π Declaration:NavigatorTest03.tsx
- 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.
NavigatorTest04
-
π Declaration:NavigatorTest04.tsx
- 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.
NavigatorTest05
-
π Declaration:NavigatorTest05.tsx
- 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.
- Shows having react and native (i.e.
- 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.
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).
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