github.com/wix/react-native-navigation

React Native Navigation v2 (WIP)

We are rebuilding react-native-navigation

• Why?
• Where is it standing now?
• Getting Started
• Usage

Why Rebuild react-native-navigation?

A New Improved Core Architecture

react-native-navigation has a few issues which are unsolvable in it’s current architecture.
These issues originate 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. This covers most use cases but there are some edge cases:

• 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 as a prop it’s containerId. Whenever you want to perform an action from that screen you need to pass the containerId to the function:

Navigator.pop(this.props.containerId)

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.

Where is it standing now?

v2 currently supports most of react-native-navigation’s basic functions but it is still behind v1. Here is the full comparison of features between v1 and v2 (will be updated regulary):

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	Contribute
dismissFab	✅	/ Android specific	Contribute
showSnackBar	✅	/ Android specific	Contribute
dismissSnackBar	✅	/ Android specific	Contribute
showLightBox	✅	Contribute	Contribute
dismissLightBox	✅	Contribute	Contribute
handleDeepLink	✅	Contribute	Contribute
setButtons	✅	Contribute	Contribute
setTitle	✅	✅	✅
toggleDrawer	✅	Contribute	Contribute
toggleTabs	✅	in development	Contribute
setTabBadge	✅	Contribute	Contribute
switchToTab	✅	in development	Contribute
toggleNavBar	✅	Contribute	Contribute
Screen Visibility	✅	✅	✅

Styles

Note: properties who begin with 'navBar' in v1 are now named 'topBar' to avoid confusion with the android native bottom nav bar.

	v1	v2 iOS	v2 Android
topBarBackgroundColor	✅	in development	Contribute
topBarTextFontSize	✅	in development	Contribute
topBarTextFontFamily	✅	in development	Contribute
topBarBackgroundColor	✅	in development	Contribute
topBarButtonColor	✅	in development	Contribute
topBarHidden	✅	in development	Contribute
topBarHideOnScroll	✅	in development	Contribute
topBarTranslucent	✅	in development	Contribute
topBarTransparent	✅	in development	Contribute
topBarNoBorder	✅	Contribute	Contribute
drawUnderTabBar	✅	Contribute	Contribute
drawUnderTopBar	✅	Contribute	Contribute
statusBarBlur	✅	Contribute	Contribute
topBarBlur	✅	Contribute	Contribute
tabBarHidden	✅	Contribute	Contribute
statusBarTextColorScheme	✅	in development	/ iOS specific
statusBarTextColorSchemeSingleScreen	✅	in development	/ iOS specific
navBarSubtitleColor	✅	Contribute	Contribute
navBarSubtitleFontFamily	✅	Contribute	Contribute
screenBackgroundColor	✅	in development	Contribute
orientation	✅	Contribute	Contribute
statusBarHideWithTopBar	✅	Contribute	Contribute
statusBarHidden	✅	Contribute	Contribute
disabledBackGesture	✅	Contribute	/ iOS specific
screenBackgroundImageName	✅	Contribute	Contribute
rootBackgroundImageName	✅	Contribute	Contribute

Element tranisitions, adding buttons and styles are not yet implemented. Contribute

Getting started with v2

If v2 supports everything you need for your app we encourage you to use it.

Installation

1. Download react-native-navigation v2

yarn add react-native-navigation@alpha

iOS

1. In Xcode, in Project Navigator (left pane), right-click on the Libraries > Add files to [project name]. Add ./node_modules/react-native-navigation/lib/ios/ReactNativeNavigation.xcodeproj (screenshots)

2. In Xcode, in Project Navigator (left pane), click on your project (top) and select the Build Phases tab (right pane). In the Link Binary With Libraries section add libReactNativeNavigation.a (screenshots)

3. In Xcode, in Project Navigator (left pane), click on your project (top) and select the Build Settings tab (right pane). In the Header Search Paths section add $(SRCROOT)/../node_modules/react-native-navigation/lib/ios. Make sure on the right to mark this new path recursive (screenshots)

4. In Xcode, under your project files, modify AppDelegate.m. add:

#import <ReactNativeNavigation/ReactNativeNavigation.h>

remove everything in the method didFinishLaunchingWithOptions and add:

NSURL *jsCodeLocation = [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index.ios" fallbackResource:nil];
[ReactNativeNavigation bootstrap:jsCodeLocation launchOptions:launchOptions];

Android

1. Add the following in android/settings.gradle.

   include ':react-native-navigation'
   project(':react-native-navigation').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-	navigation/lib/android/app/')
   

2. Update project dependencies in android/app/build.gradle.

   android {
   	compileSdkVersion 25
   	buildToolsVersion "25.0.1"
   	...
   }
   
   dependencies {
   	compile fileTree(dir: "libs", include: ["*.jar"])
   	compile "com.android.support:appcompat-v7:23.0.1"
   	compile "com.facebook.react:react-native:+"
   	compile project(':react-native-navigation')
   }
   

3. In MainActivity.java it should extend com.reactnativenavigation.controllers.SplashActivity instead of ReactActivity.

   This file can be located in android/app/src/main/java/com/yourproject/.

   import com.reactnativenavigation.controllers.SplashActivity;
   
   public class MainActivity extends SplashActivity {
   
   }
   

   If you have any react-native related methods, you can safely delete them.

4. In MainApplication.java, add the following

   import com.reactnativenavigation.NavigationApplication;
   
   public class MainApplication extends NavigationApplication {
   
   	@Override
   	public boolean isDebug() {
   		// Make sure you are using BuildConfig from your own application
   		return BuildConfig.DEBUG;
   	}
   
   	protected List<ReactPackage> getPackages() {
   		// Add additional packages you require here
   		// No need to add RnnPackage and MainReactPackage
   		return Arrays.<ReactPackage>asList(
   			// eg. new VectorIconsPackage()
   		);
   	}
   
   	@Override
   	public List<ReactPackage> createAdditionalReactPackages() {
   		return getPackages();
   	}
   }
   

   Make sure that isDebug and createAdditionalReactPackages methods are implemented.

5. Update AndroidManifest.xml and set android:name value to .MainApplication

   <application
   	android:name=".MainApplication"
   	...
   />
   

Usage

Top Screen API

Navigation

import Navigation from 'react-native-navigation';

Events - On App Launched

How to initiate your app.

Navigation.events().onAppLaunched(() => {
    Navigation.setRoot({
      container: {
        name: 'navigation.playground.WelcomeScreen'
      }
    });
  });

registerContainer(screenID, generator)

Every screen component in your app must be registered with a unique name. The component itself is a traditional React component extending React.Component.

Navigation.registerContainer(`navigation.playground.WelcomeScreen`, () => WelcomeScreen);

setRoot({params})

Start a Single page app with two side menus:

Navigation.setRoot({
      container: {
        name: 'navigation.playground.WelcomeScreen'
      },
      sideMenu: {
        left: {
          container: {
            name: 'navigation.playground.TextScreen',
            passProps: {
              text: 'This is a left side menu screen'
            }
          }
        },
        right: {
          container: {
            name: 'navigation.playground.TextScreen',
            passProps: {
              text: 'This is a right side menu screen'
            }
          }
        }
      }
    });

Start a tab based app:

Navigation.setRoot({
      tabs: [
        {
          container: {
            name: 'navigation.playground.TextScreen',
            passProps: {
              text: 'This is tab 1',
              myFunction: () => 'Hello from a function!'
            }
          }
        },
        {
          container: {
            name: 'navigation.playground.TextScreen',
            passProps: {
              text: 'This is tab 2'
            }
          }
        }
      ]
    });

Screen API

push(params)

Push a new screen into this screen's navigation stack.

Navigation.push(this.props.containerId, {
      name: 'navigation.playground.PushedScreen',
      passProps: {}
    });

pop(containerId)

Pop the top screen from this screen's navigation stack.

Navigation.pop(this.props.containerId);

popTo(params)

Navigation.popTo(this.props.containerId, this.props.previousScreenIds[0]);

popToRoot()

Pop all the screens until the root from this screen's navigation stack

Navigation.popToRoot(this.props.containerId);

showModal(params = {})

Show a screen as a modal.

Navigation.showModal({
      container: {
        name: 'navigation.playground.ModalScreen',
        passProps: {
            key: 'value'
        }
      }
    });

dismissModal(containerId)

Dismiss modal.

Navigation.dismissModal(this.props.containerId);

dismissAllModals()

Dismiss all the current modals at the same time.

Navigation.dismissAllModals();

Screen Lifecycle - onStop() and onStart()

The onStop() and onStart() functions are lifecycle functions that are added to the screen and run when a screen apears and disappears from the screen. To use them simply add them to your component like any other react lifecycle function:

class LifecycleScreen extends Component {
  constructor(props) {
    super(props);
    this.state = {
      text: 'nothing yet'
    };
  }

  onStart() {
    this.setState({ text: 'onStart' });
  }

  onStop() {
    alert('onStop'); //eslint-disable-line
  }

  componentWillUnmount() {
    alert('componentWillUnmount'); //eslint-disable-line
  }

  render() {
    return (
      <View style={styles.root}>
        <Text style={styles.h1}>{`Lifecycle Screen`}</Text>
	<Text style={styles.h1}>{this.state.text}</Text>
      </View>
    );
  }
}