react-native-navigation/docs/README.md

React Native Navigation v2 (WIP)

We are rebuilding react-native-navigation.

As we are in stage alpha, expect breaking API changes or use a specific version (for example “2.0.1234”)

• Why?
• v2 Roadmap
• v1 vs v2 feature comparison
• Documentation
• Contributing

Why Rebuild react-native-navigation?

A New & Improved Core Architecture

react-native-navigation has a few issues which are unsolvable in its current architecture. These issues stem from the same problem: you cannot specify on which screen you wish to make an action. Whenever you want to push a screen, show a modal or any other action, the action defaults to originate from your current screen. In most cases this is fine, but becomes problematic in specific edge cases. For example:

• What if you want to update your navbar icons and the user pops the screen? Your icons might update on the wrong screen.
• What if you want to push a screen as a result of a redux action?

There are ways to solve some of these problems in v1 but they are not straightforward. We want to change that.

New API

To solve this problem in v2, every screen receives its componentId as a prop. Whenever you want to perform an action from that screen you need to pass the componentId to the function:

Navigator.pop(this.props.componentId)

Another big architectural change is that now you can compose arbitrary native layout hierarchies, and assign a custom id to each and control them individually.

Built for Contributors

Currently, it requires a lot of work to accept pull requests. We need to manually make sure that everything works before we approve them because v1 is not thoroughly tested.
v2 is written with contributors in mind from day one.

Written In TDD

v2 is written in Test Driven Development. We have a test for every feature including features that are not implemented yet. This makes accepting pull requests extremely easy: If our tests pass, your pull request is accepted.

v2 Roadmap

Current Priorities

1) buttons in Android 2) showOverlay in iOS 3) showOverlay in Android 4) async commands 5) currentTab 6) change Options to be nested 7) topTabs in both platforms, with API implications

Top API

Top API	iOS	Android
setRoot	✅	✅
registerComponent	✅	✅
component	✅	✅
sideMenu	✅	✅
tabs	✅	✅
External Component	✅	✅
splitView	Contribute	Contribute

Screen API

Screen API	iOS	Android
push	✅	✅
pop	✅	✅
popToRoot	✅	✅
resetTo	✅	✅
showModal	✅	✅
dismissModal	✅	✅
showOverlay	✅	✅
dismissOverlay	✅	✅
customTransition	✅	Contribute
Screen Visibility	✅	✅
async commands (await push)	✅	✅

Navigation Options

topBar	iOS	Android	Contributor(s)
title	✅	✅	Wix
textColor	✅	✅	Wix
textFontSize	✅	✅	Wix
textFontFamily	✅	✅	Wix
backgroundColor	✅	✅	Wix
buttonColor	✅	✅	Wix
hidden	✅	✅	Wix
hideOnScroll	✅	✅	Wix
translucent	✅	Contribute	Wix
transparent	✅	Contribute
noBorder	✅	Contribute	@gtchance
drawUnder	✅	✅
blur	✅	Contribute	@gtchance
custom component	✅	✅
background component	✅	Contribute
subtitleColor	✅	Contribute
subtitleFontFamily	Contribute	Contribute
largeTitle (iOS 11)	✅	/iOS Specific

tabBar	iOS	Android	Contributor(s)
drawUnder	✅	✅
hidden	✅	✅	@gtchance
tabBadge	✅	✅	Wix
currentTab by Index	✅	✅	Wix
currentTab by componentId	✅	✅	Wix

buttons	iOS	Android	Contributor(s)
id	✅	✅	@Johan-dutoit
testID	✅	✅	@Johan-dutoit
color	✅	✅	@Johan-dutoit
icon	✅	✅	@Johan-dutoit
disableTint	✅	✅	@Johan-dutoit
fontSize	✅	✅	@Johan-dutoit
fontWeight	✅	Contribute

statusBar	iOS	Android	Contributor(s)
textColorScheme	✅	Contribute
textColorSchemeSingleScreen	✅	/ iOS specific
blur	✅	Contribute	@gtchance
hideWithTopBar	✅	Contribute	@gtchance
hidden	✅	Contribute	Wix

other	iOS	Android	Contributor(s)
screenBackgroundColor	✅	Contribute	Wix
orientation	✅	✅	Wix
disabledBackGesture	✅	/ iOS specific
screenBackgroundImageName	✅	Contribute
rootBackgroundImageName	✅	Contribute
sideMenuVisible	✅	✅

v1 vs v2 Feature Comparison

Here is the full comparison of features between v1 and v2 (will be updated regularly):

Top Level API

API	v1	v2
startTabBasedApp	✅	✅
startSinglePageApp	✅	✅
registerScreen	✅	✅
drawer	✅	✅

Screen API

API	v1	v2 iOS	v2 Android
push	✅	✅	✅
pop	✅	✅	✅
showModal	✅	✅	✅
popToRoot	✅	✅	✅
resetTo	✅	✅	✅
dismissModal	✅	✅	✅
dismissAllModals	✅	✅	✅
showContextualMenu	✅	/ Android specific	Contribute
dismissContextualMenu	✅	/ Androic specific	Contribute
showFab	✅	/ Android specific	✅
dismissFab	✅	/ Android specific	✅
showSnackBar	✅	/ Android specific	Contribute
dismissSnackBar	✅	/ Android specific	Contribute
showLightBox	✅	:x:	:x:
dismissLightBox	✅	:x:	:x:
showOverlay	:x:	✅	✅
dismissOverlay	:x:	✅	✅
handleDeepLink	✅	Contribute	Contribute
Screen Visibility	✅	✅	✅

Styles

Note: v1 properties with names beginning with ‘navBar’ are replaced in v2 with properties beginning with ‘topBar’ to avoid confusion with the Android native bottom nav bar.

	v1	v2 iOS	v2 Android
topBarTextColor	✅	✅	✅
topBarTextFontSize	✅	✅	✅
topBarTextFontFamily	✅	✅	✅
topBarBackgroundColor	✅	✅	✅
topBarButtonColor	✅	✅	✅
topBarHidden	✅	✅	✅
topBarHideOnScroll	✅	✅	✅
topBarTranslucent	✅	✅	Contribute
topBarTransparent	✅	✅	Contribute
topBarNoBorder	✅	✅	Contribute
drawUnderTabBar	✅	✅	✅
drawUnderTopBar	✅	✅	✅
statusBarBlur	✅	✅	Contribute
topBarBlur	✅	✅	Contribute
tabBarHidden	✅	✅	✅
statusBarTextColorScheme	✅	✅	/ iOS specific
statusBarTextColorSchemeSingleScreen	✅	✅	/ iOS specific
topBarSubtitleColor	✅	✅	Contribute
topBarSubtitleFontFamily	✅	✅	Contribute
screenBackgroundColor	✅	✅	Contribute
orientation	✅	✅	✅
statusBarHideWithTopBar	✅	✅	Contribute
statusBarHidden	✅	✅	Contribute
disabledBackGesture	✅	✅	/ iOS specific
screenBackgroundImageName	✅	✅	Contribute
rootBackgroundImageName	✅	✅	Contribute
setButtons	✅	✅	✅
title	✅	✅	✅
toggleDrawer	✅	✅	✅
setTabBadge	✅	✅	✅
switchToTab	✅	✅	✅
topBar react component	✅	✅	✅
Shared Element Transition	:x:	✅	Contribute
splitViewScreen	:x:	Contribute	Contribute