{"id":14974354,"url":"https://github.com/bamlab/flow-navigator","last_synced_at":"2025-10-27T06:32:15.882Z","repository":{"id":207003102,"uuid":"718054326","full_name":"bamlab/flow-navigator","owner":"bamlab","description":"A flow navigator for react-navigation","archived":false,"fork":false,"pushed_at":"2024-03-18T14:10:00.000Z","size":4513,"stargazers_count":44,"open_issues_count":3,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-01T03:24:08.215Z","etag":null,"topics":["flows","react-native","react-navigation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bamlab.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-11-13T09:27:12.000Z","updated_at":"2024-12-26T01:12:07.000Z","dependencies_parsed_at":"2024-01-29T12:53:30.713Z","dependency_job_id":"1f547632-09a6-4c01-bd05-3c96e3d4c525","html_url":"https://github.com/bamlab/flow-navigator","commit_stats":null,"previous_names":["bamlab/flow-navigator"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamlab%2Fflow-navigator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamlab%2Fflow-navigator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamlab%2Fflow-navigator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamlab%2Fflow-navigator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bamlab","download_url":"https://codeload.github.com/bamlab/flow-navigator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238455168,"owners_count":19475404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flows","react-native","react-navigation"],"created_at":"2024-09-24T13:50:26.709Z","updated_at":"2025-10-27T06:32:14.650Z","avatar_url":"https://github.com/bamlab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Alt text](image.png)\n# Flow Navigator for React Navigation\n\n## Simplifying Flow Navigation in React Native\n\nFlow Navigator provides a simplified API for managing navigation flows in your React Native applications with [React Navigation](https://reactnavigation.org/). 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.\n\n## Features\n\n- **Simplified Flow Management**: Get a comprehensive overview of your flow in a single location. This allows new developers to quickly understand the entire flow without the need to examine each page individually.\n- **Separation of responsibility**: Screens are not aware of their specific position in the flow. They don't need to know which page is next; they simply navigate to the next page in the flow.\n- **Declarative Screen Ordering**: Define the order of screens in your navigation flow declaratively, ensuring a clear and maintainable navigation structure.\n\n## Installation\n\nThe flow navigator is built on top of react-navigation's native stack navigator. So it requires both [react-navigation](https://reactnavigation.org/docs/getting-started/) and the [native stack navigator](https://reactnavigation.org/docs/native-stack-navigator/) installed.\n\nTo install the flow navigator, run:\n\n```bash\nyarn add @bam.tech/flow-navigator\n# or\nnpm install @bam.tech/flow-navigator\n```\n\n## Usage\n### Basic usage\n\n```tsx\nimport { createFlowNavigator } from '@bam.tech/flow-navigator';\n\nconst FlowNavigator = createFlowNavigator();\n\nexport const FlowNavigatorExample = () =\u003e {\n   // Define your screens and their order in the flow\n  return (\n    \u003cFlowNavigator.Navigator\u003e\n      \u003cFlowNavigator.Screen name=\"Step1\" component={Step1Page} /\u003e\n      \u003cFlowNavigator.Screen name=\"Step2\" component={Step2Page} /\u003e\n      \u003cFlowNavigator.Screen name=\"Step3\" component={Step2Page} /\u003e\n    \u003c/FlowNavigator.Navigator\u003e\n  );\n};\n```\n\nIn each screen component, you can navigate through the flow using:\n\n```tsx\nimport { useFlow } from '@bam.tech/flow-navigator';\n\nconst Step1Page = () =\u003e {\n  const { goToNextStep, goToPreviousStep, currentStep } = useFlow();\n\n  return (\n    \u003cButton title=\"Go to next page\" onPress={() =\u003e goToNextStep()} /\u003e\n  )\n};\n```\n\nYou can find a fully working example in the [example](./example/App.tsx) folder.\n\n![Alt text](\u003cNov-15-2023 15-29-57.gif\u003e)\n\n\n### Define conditional steps\n\nIn 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.\n\nHere'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. In our case, we use jotai to store our user data locally.\n\n```tsx\nimport { createFlowNavigator } from '@bam.tech/flow-navigator';\n\nexport const flagAtom = atom(false);\n\nconst FlowNavigator = createFlowNavigator();\n\nexport const FlowNavigatorExample = () =\u003e {\n  const [flag] = useAtom(flagAtom);\n\n  return (\n    \u003cFlowNavigator.Navigator\u003e\n      \u003cFlowNavigator.Screen name=\"Step1\" component={Step1Page} /\u003e\n      {flag \u0026\u0026 \u003cFlowNavigator.Screen name=\"Step2\" component={Step2Page} /\u003e}\n      \u003cFlowNavigator.Screen name=\"Step3\" component={Step3Page} /\u003e\n    \u003c/FlowNavigator.Navigator\u003e\n  );\n};\n```\n\nIn this example, the Step2 screen is only included in the flow if hasToPassStep2 evaluates to true.\n\nYou can enable or disable routes at anytime in your flow by setting your boolean state: `setFlag(false)`\n\n```tsx\nimport { useFlow } from '@bam.tech/flow-navigator';\n\nexport const Step1Page = () =\u003e {\n  const {goBack, goToNextStep} = useFlow();\n  const [flag] = useAtom(flagAtom);\n\n  const onNextPress = async () =\u003e {\n    setFlag(false);\n    goToNextStep();\n  };\n\n  const onBackPress = () =\u003e {\n    goBack();\n  };\n\n  return (\n    \u003cView style={styles.container}\u003e\n      \u003cText style={styles.pageTitle}\u003eCurrent page: 1\u003c/Text\u003e\n      \u003cFlowInfos /\u003e\n      \u003cButton title=\"next\" onPress={onNextPress} /\u003e\n      \u003cButton title=\"back\" onPress={onBackPress} /\u003e\n    \u003c/View\u003e\n  );\n};\n```\n\nYou can check out a fully working example in the [example](./example/src/FlowNavigatorExample.tsx) folder\n\n### Define steps with several screens\n\nIn 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](https://reactnavigation.org/docs/group/) or [Nested navigators](https://reactnavigation.org/docs/screen-options-resolution/). \nExamples of both approaches can be found in the example folder.\nWe 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. Note that all the pages of a subnavigator will correspond to one increment of the progress index, that will stay constant throughout the whole step.\n\n### Use cases\nFlows are sequences of pages with a pre-defined order, guiding users through a specific process within your app. Whether complex or straightforward, flows are a fundamental part of the user experience in many applications. Here are some common examples where Flow Navigator can be particularly useful:\n- Onboarding flow\n- Post publication flow\n- Subscription flow\n- Shopping cart checkout process\n- Survey of feedback flow\n- Profile setup flow\n\n## API definition\n\n### FlowNavigator\nThe Flow Navigator is built upon the foundation of the [native stack](https://reactnavigation.org/docs/native-stack-navigator/#api-definition), it inherits the same API.\n\n### useFlow\nInside a screen defined below a Flow Navigator, you can use the `useFlow`\n`useFlow` provides the following helpers:\n- `goToNextStep`: To navigate to the next step in the flow, based on the order of the screens in the navigation flow.\n- `goToPreviousStep`: To navigate to the previous step in the flow, based on the order of the screens in the navigation flow.\n- `quitFlow`: To exit the flow.\n\n`useFlow` also provides information about the current step of the flow. It contains the following properties:\n\n- `currentStep`: A string representing the identifier of the current step in the flow. Based on the name of the screen.\n- `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.\n- `canGoToPreviousStep`: A boolean indicating whether navigation to a previous step is possible.\n- `canGoToNextStep`: A boolean indicating whether navigation to the next step is possible.\n\n## Contributing\nPull requests and feature suggestions are more than welcome!\n\n### Testing your changes\nYou can try out your changes in the example folder.\nUse [yarn link](https://classic.yarnpkg.com/lang/en/docs/cli/link/) to try out your local library version:\n\n1. At the root directory of `@bam.tech/flow-navigator`, run\n```bash\n  cd packages/lib\n  yarn link\n```\n2. Link in the example project:\n```bash\n  cd packages/example\n  yarn link \"@bam.tech/flow-navigator\"\n```\n\n3. Make your changes in the lib, and transpile the code from TS to JS, to be able to try out the changes in the example. You can run this command at the root of the repo\n```bash\n  yarn transpile:lib\n```\n\n4. Unlink when done, once the changes are published:\n```bash\n  cd packages/example\n  yarn unlink \"@bam.tech/flow-navigator\"\n  yarn install\n```\n\n### Publishing the package\n1. Increment the package.json in ./packages/lib/package.json\n2. Commit the change git commit -m \"chore: bump version\"\n2. Add a tag matching the version \n```bash\n   git tag vx.x.x \u0026\u0026 git push --tags\n```\n3. Then publish the package: run this command at the root of the repo\n```bash\n  yarn publish:lib\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbamlab%2Fflow-navigator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbamlab%2Fflow-navigator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbamlab%2Fflow-navigator/lists"}