Navigation React (problems and not detailed documentation)

[FernetB]

Ionic version:

[] 4.x
[x] 5.x

I'm submitting a ...

[ ] bug report
[x] feature request

Hi, I was using ionic react for the past few years, and the only thing that i never understood well was the navigation.

I read the documentation several times and i think is not suited for all the cases.

In the present, ionic leave all your pages mounted, and there are 2 ways of remove it from the DOM programatically

1 - if you go from A -> B history.goBack() -> A then B is removed from the DOM,
2 - if you go from A -> B navigate(C, "forward", "pop") -> C then B is removed from the DOM (navigate is from useIonRouter or useContext(navContext)

With this aproaches you can remove 1 page from the DOM, but what if you want to remove a bunch of pages?

Well if you have something like this: HOME -> A -> B-> .... -> Z -> HOME and you want to unmount all the pages from A to Z because that was a flow that was already completed then u could do this:

1 - Put HOME in the main router outlet
2 - Put all the pages from A to Z in a nested router outlet
3 - When on Z use navigate(HOME, "forward", "pop") and this will unmount the router oulet and with that all the pages in that outlet

This case is not documented and not explained at all, (in fact nothing in terms of mounted pages is documented, not even the hook and context used before)

And there are problems from this that are also not warned like the fact that if you use state between pages and use useLocation to consume that state you will have problems because of mounted pages:

if you go from A -> B with stateB -> C with stateC the page B that use useLocation to get the stateB will change to stateC because you are now in C but B is mounted so the app may crash, in a case when you were doing stateB.person.dni on B but you are now in page C with stateC that has not the object person, then B will crash for doing dni of undefined

Also the strategy of nested IonRouterOutles is not the silver bullet, because you will have cases like

TABS -> HOME -> A -> ... -> X -> Z -> HOME -> TABS

in wich if you wanna go back from HOME -> TABS you will need to do something in HOME like put a backButton listener to do navigate(TABS, "forward", "pop") because the hardware back button will do a goBack that will go to page X (because Z was not only unmounted but also popped from the history, and not only this, you also will notice of wrong transition between routerOutlets)

With all that, it will be EXTREMELY nice if you come with a more detailed and in deep documentation of the react navigation and how to use it properly.

I have +4 years of experience with ionic and the navigation always is a major problem, because is one of the most important thing o an app

Thanks and I hope someone read this!

Cheers.

Ionic info:

Ionic:

   Ionic CLI       : 6.19.0
   Ionic Framework : @ionic/react 5.9.1

Capacitor:

   Capacitor CLI      : 4.1.0
   @capacitor/android : 4.1.0
   @capacitor/core    : 4.1.0
   @capacitor/ios     : 4.1.0

Utility:

   cordova-res : 0.15.1
   native-run  : 1.7.0

System:

   NodeJS : v14.17.0
   npm    : 6.14.13
   OS     : Windows 10

[liamdebeasi]

Do you have a sample repo that shows the issue you are reporting?

[FernetB]

But is a feature request not an issue, I do not know what u tried to do with the react navigation and because of that i can't know if there are bugs in what i'm describing, or is the normal behaviour, but most of the problems are in fact because of the lack of documentation, and the "state" problem, does not need reproduction because is what's going to happen if you have mounted pages in the dom in combine with useLocation hook

[liamdebeasi]

We first need to understand the problems you are running into because the feature request is designed to solve those problems.

[FernetB]

The first and most important problem is the lack of documentation there are nothing that tell's you how the mount/unmount of the pages really works, also there is no documentation of both the useIonRouter and navContext, nothing of the posibles problems of using the useLocation hook (that is widely used by the react developers), and i think that would be extremely nice if you bring a guide of how to properly use the navigation in complex cases that are common in several apps like going from TABS -> HOME -> FLOW -> SUCCESS -> HOME -> TABS

Another question that is not anwered is:
The idea of the ion router usage is just leave all mounted and do all in the lifecycle hooks? But this eventually would make your entire app mounted in the DOM, that will lead to perfomance issues because the DOM tree will be extremely big

[liamdebeasi]

There are several concerns here:

1. There is no documentation on the mount/unmount behavior in Ionic React.

The mount/unmount behavior can be found on the Ionic React Lifecycle Docs. In general, developers should not try to manipulate or work against the mount/unmount behavior. This behavior exists so that state can be preserved on older pages and enables the swipe to go back feature on iOS.

---

2. There is no documentation on how to use useIonRouter and navContext.

I've added docs for useIonRouter here: ionic-team/ionic-docs#2888

navContext is a private API which is why it does not have public documentation.

---

3. There is minimal guidance for how to do complex tabs navigation.

The Ionic React Navigation Guide has docs on how to work with tabs.

In this particular case, you have the following flow:

TABS -> HOME -> FLOW -> SUCCESS -> HOME -> TABS

This is not something you should do because you are mixing history across stacks. Stack-based navigation (which is what most mobile apps use) comes with restrictions for how you can navigate in the app.

Instead, your flow should look like this:

TABS -> HOME -> FLOW -> SUCCESS -> (go back) FLOW -> (go back) HOME -> (go back) TABS.

This will avoid mixing history across stacks. For the FLOW --> SUCCESS part you may want to consider using an ion-modal with ion-nav instead since it sounds like those pages are temporary.

---

4. Mounting multiple pages will cause performance issues.

Inactive pages are hidden using display: none, so there should be minimal performance impact. However, if you are running into Ionic-related performance issues I would encourage you to open an issue and provide a reproduction case.

[FernetB]

In the 3rd case I respecfully disagree, I found it fairly common to have cases on wich u have severals steps and then on the success u want to navigate to the Home instead of going back multiples times because there were steps that u already completed, and there are not an easy solution for that.

The useLocation problem is still present and not warned and it should be because react routing uses historiy and is normal for people to use states

[FernetB]

I think that if you have something like the popToTop method on the react navigation, that takes you back to the first screen in the stack, dismissing all the others would be awesome

[liamdebeasi]

I think that if you have something like the popToTop method on the react navigation, that takes you back to the first screen in the stack, dismissing all the others would be awesome

We do plan on offering better tooling for navigating backwards by multiple views. Ideally the experience would be something like this: ionRouter.goBackToPage('TABS') which would bring you back to the original tabs route that way you do not need to go back multiple times manually.

---

The useLocation problem is still present and not warned and it should be because react routing uses historiy and is normal for people to use states

Can you file a separate issue for this?

---

I am going to close this issue since all the actionable items have been completed. However, let me know if you have other questions. Here are the resolutions of this thread:

1. The useIonRouter documentation has been released: docs(react): add example for useIonRouter ionic-docs#2888 (Should be live on the docs website soon)
2. A separate issue should be filed with a reproduction for the useLocation behavior.
3. We are working on router changes that will improve the experience when jumping between routes. This work is being tracked internally, but we do plan to have a public testing period when it is ready.

[ionitron-bot]

Thanks for the issue! This issue is being locked to prevent comments that are not relevant to the original issue. If this is still an issue with the latest version of Ionic, please create a new issue and ensure the template is fully filled out.