@bam.tech/flow-navigator

Flow Navigator for React Navigation

Simplifying Flow Navigation in React Native

Flow Navigator provides a simplified API for managing navigation flows in your React Native applications with React Navigation. It abstracts the complexity of flow management, allowing individual screens to navigate through the flow using simple methods like goToNextStep and goToPreviousStep, without the need to understand the entire navigation stack, or knowing which page exactly is the next one.

Features

• Simplified Flow Management: Easily manage the navigation flow without the need for screens to be aware of their position in the flow.
• Declarative Screen Ordering: Define the order of screens in your navigation flow declaratively, ensuring a clear and maintainable navigation structure.

Installation

yarn add @bam.tech/flow-navigator
# or
npm install @bam.tech/flow-navigator

Usage

Basic usage

import { FlowNavigator } from '@bam.tech/flow-navigator';

const FlowNavigator = createFlowNavigator();

export const FlowNavigator = () => {
   // Define your screens and their order in the flow
  return (
    <FlowNavigator.Navigator screenOptions={{ headerShown: false }}>
      <FlowNavigator.Screen name="Step1" component={Step1Page} />
      <FlowNavigator.Screen name="Step2" component={Step2Page} />
      <FlowNavigator.Screen name="Step3" component={Step2Page} />
    </FlowNavigator.Navigator>
  );
};

In each screen component, you can navigate through the flow using:

import { useFlowStatus } from '@bam.tech/flow-navigator';
import { useNavigation, ParamListBase } from '@react-navigation/native';
import { FlowNavigationProp } from '@bam.tech/flow-navigator';

const Step1Page = () => {
  const { goToNextStep, goToPreviousStep } = useNavigation<FlowNavigationProp<ParamListBase>>();
  const { currentStep } = useFlowStatus();

  return (
    <Button title="Go to next page" onPress={() => goToNextStep()} />
  )
};

You can find a fully working example in the example folder.

Define conditional steps

In certain scenarios, a flow may include steps that are conditional. These steps might be dependent on user-specific conditions or based on whether certain actions have already been completed. You can manage such conditional steps declaratively in your navigation flow.

Here's an example where "Step 2" is conditionally displayed based on the hasToPassStep2 variable. This variable could be a piece of data fetched from the backend or a state within your application.

import { FlowNavigator } from '@bam.tech/flow-navigator';

const FlowNavigator = createFlowNavigator();

export const App = () => {
  const hasToPassStep2 = /* your condition here */;

  return (
    <FlowNavigator.Navigator screenOptions={{ headerShown: false }}>
      <FlowNavigator.Screen name="Step1" component={Step1Page} />
      {hasToPassStep2 && <FlowNavigator.Screen name="Step2" component={Step2Page} />}
      <FlowNavigator.Screen name="Step3" component={Step3Page} />
    </FlowNavigator.Navigator>
  );
};

In this example, the Step2 screen is only included in the flow if hasToPassStep2 evaluates to true.

You can check out a fully working example in the example folder

Define steps with several screens

In some scenarios, a single step in a flow may encompass several screens. To group these screens within one step, you have a couple of options: using Groups or Nested navigators. Examples of both approaches can be found in the example folder. We recommend using groups if they suit your use-case. However, one limitation to note is that the currentStep will reflect the name of the screen that is currently focused, not the group name. So all the screens in the step won't have the same currentStep value. With nested navigator, currentStep is the name of the subnavigator, which provides a more cohesive representation of the step.

API definition

FlowNavigator

The Flow Navigator is built upon the foundation of the native stack, it inherits the same API.

Helpers

The flow navigator adds the following methods to the navigation prop:

• goToNextStep: To navigate to the next step in the flow, based on the order of the screens in the navigation flow.
• goToPreviousStep: To navigate to the previous step in the flow, based on the order of the screens in the navigation flow.
• quitFlow: To exit the flow.

useFlowStatus

Inside a screen defined below a Flow Navigator, you can use the useFlowStatus, which provides information about the current step of the flow. It contains the following properties:

• currentStep: A string representing the identifier of the current step in the flow. Based on the name of the screen.
• progress: A number indicating the progress through the flow. It is calculated as the ratio of the current index to the total number of routes.
• canGoToPreviousStep: A boolean indicating whether navigation to a previous step is possible.
• canGoToNextStep: A boolean indicating whether navigation to the next step is possible.

Contributing

Pull requests and feature suggestions are more than welcome!