RFC: Option to provide wrapping components to support Suspense boundaries

[levibuzolic]

Moved from #11133

For apps that use React.Suspense (Relay, React Query etc.) and/or error boundaries for each screen it can be awkard to wrap every screen with the required components in userland.

Problem example

Given the following screen and suspense/error boundary wrappers:

function HomeScreen() {
  const data = useQuery(); // A hook that will suspend
  return <Text>{data.text}</Text>;
}

function SuspenseBoundary({children}) {
  return (
    <ErrorBoundary>
      <React.Suspense fallback={<Text>Loading...</Text>}>
        {children}
      </React.Suspense>
    </ErrorBoundary>
  );
}

There are a few user-land options for handling wrapping every screen:

Screen.children

This opts out of the React.PureComponent optimisations of React Navigation and becomes quite verbose with many routes.

Example

function NavigatorRoot() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home">
        {(props) => (
          <SuspenseBoundary>
            <HomeScreen {...props} />
          </SuspenseBoundary>
        )}
      </Stack.Screen>
    </Stack.Navigator>
  );
}

Manually wrapping

This keeps the optimisations, but still painful with many routes.

Example

function NavigatorRoot() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={HomeScreenWrapper} />
    </Stack.Navigator>
  );
}

function HomeScreenWrapper(props) {
  return (
    <SuspenseBoundary>
      <HomeScreen {...props} />
    </SuspenseBoundary>
  );
}

Component factory

This is the currently the best user-land solution, but if we had support for providing a wrapper at the navigator level, this could be much simpler.

Example

const HomeScreen = factoryToWrapWithSuspense(require('./HomeScreen'));

function NavigatorRoot() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={HomeScreen} />
    </Stack.Navigator>
  );
}

function factoryToWrapWithSuspense(module) {
  const Component = module.default;

  return (props) => (
    <SuspenseBoundary>
      <Component {...props} />
    </SuspenseBoundary>
  );
}

Proposed solution

A wrapper option added to each navigator which allows the user to supply a component to wrap the content of the screen. This allows consistent behaviour across an entire navigator in addition to flexibility to alter the behaviour for each screen should that be required.

function NavigatorRoot() {
  return (
    <Stack.Navigator screenOptions={{wrapper: SuspenseBoundary}}>
      <Stack.Screen name="Home" component={HomeScreen} />
      <Stack.Screen name="ScreenWithoutWrapper" component={AnotherScreen} options={{wrapper: null}} />
    </Stack.Navigator>
  );
}

[levibuzolic]

It was also raised in #11133 by @xotahal that a similar solution might be useful for providing context to a screen's header. The implementation in the PR does not address this use case effectively, however the proposal of a wrapper option may still be suitable.

To provide context to a screen's header, the wrapping component slot would need to sit at a higher level, however this becomes problematic for stack navigators using the floating header which is not rendered per-screen but instead has a single header shared across multiple screens.

In some cases wrapping the entire stack/navigator with a context provider would be desireable and sounds like something that could be well worth supporting, but I'll let @xotahal comment on wether that would be suitable for their particular use case.

I think a wrapping component at the navigator level wouldn't be suitable for Suspense because it would mean the header and the previous screens in the stack would be affected by the suspense boundary, unless stack implemented its own <Suspense> with the fallback including these components. This may still be problematic because these components will all be unmounted and remounted due to the behaviour of suspense.

To solve both use cases, there could be multiple options which provide the ability to insert a wrapping component at different levels of the stack (or other) navigator. This could be a potential foot-gun as it requires somewhat deep understanding of the internal implementation of the navigator around which level in the hierarchy is most appropriate for each use case.

[xotahal]

Ok. Let me try to describe our needs. Let's say that we have ItemDetail screen. This screen is "built" based on data of item. So we don't even know if we want to display a floating header or header as a part of the screen. We don't have "global" state management. We need to wrap the specific screen with "store" and once we unmount the screen we "discard" the state. And because of that, we need the whole screen to access the same store. We also need to compute the initialParams and options from that store.

To summarize our goal in points:

1. We need to wrap the whole screen (content + header) with the same Context (store)
2. We need to compute initialParams and options dynamically based on the store (we can't compute them at the navigation time - when we call navigation.navigate, because we don't have the store that should wrap the screen we about to navigate to)
3. We need the whole screen to go to suspense while we're computing the initialParams. So the navigation itself is immediate. Then the user sees Suspended content and after that, the header and everything is displayed.

We don't need a separate wrapper for the header and content since you can achieve it by simply wrapping those in the render function. However, I understand the reason why @levibuzolic proposing the change. It definitely simplifies the code. 👏

I don't have enough knowledge about the code of this library so I can't suggest where we should inject this context. But let me try to "think out loud" about possible changes:

const DataComponent = (props) => {
  const item = useStore(props.route.params.itemId) // goes to suspense if no data
  
  // this might be an options hot set options and params?
  // props.navigation.setOptions({ ... })  
  // props.navigation.setParams({ ... })
  
  return props.children
}

const ScreenWrapperComponent = (props) => {
   return (
     <Suspense>
       <StoreProvider><DataComponent /></StoreProvider>
     </Suspense>
   )
}

<Screen
   wrappers={() => ({
       screen: ScreenWrapperComponent, // this wraps both component and header
       component: Suspense, // this wraps only Component
       header: null, // wraps only Header
   })}
   options={(params) => {
      const item = useStore(params.itemId)
      
      return { ... }
   }}
    // this should be merged with initialParams that are static and used in the screen later
   dynamicParams={(initialParams) => {
      const item = useStore(params.itemId)
      
      return { ... }
   }}
/>

[levibuzolic]

Thanks for the context! A few quick thoughts...

The floating header behaviour is definitely going to be problematic for any solution where we want to wrap both the header and the screen, the current stack hierarchy means that we'd tear down all screens in the history, which would cause all kinds of issues. That would likely need to be reworked significantly for it to have any possibility to work.

Accessing useStore in options and dynamicParams is an interesting use case, it would mean that they would themselves have to be called as hooks internally. I think that's doable, but the suspense would likely then need to happen at the parent navigator layer.

dynamicParams seems like a alternate API to doing something like this in your route's component:

const item = useStore(params.itemId)

useEffect(() => {
  navigation.setParams({ ... })
}, [item, navigation])

One issue I see is that you'd like for the navigation to happen immediately, but then for the screen to suspend. I don't think that behaviour fits with the current model of options. The navigator needs to know the screen options before navigating, but because they're asynchronous you'd need to wait for them to resolve before navigating. I guess it could sort of work if you were okay with the parent navigator or group being the source of the screen options until the component has finished suspending.

But then in that case, this also just seems like an alternative API to doing the following in your screen component:

const item = useStore(params.itemId)

useEffect(() => {
  navigation.setOptions({ header: ... /* header could be rendered with content from item */ })
}, [item, navigation])

[satya164]

Thanks for the RFC. I currently don't have much time to focus on this so I just wanted to lay down what I have in mind for suspense and data-fetching support in React Navigation.

Each Screen could take some additional props:

• loader - It would trigger data fetching or any other async tasks after the navigation. We don't want to include any data fetching-specific functionality in React Navigation, so you'd typically use another data fetching lib such as react-query. This is also useful to implement "render as you fetch" pattern on Web when the component is lazy loaded.
• loading - Loading UI for the suspense fallback for the screen (similar to NextJS)
• error - Error UI for error boundary (similar to NextJS)

These are just my initial ideas. I'd like to spend some time learning more about how tools such as Remix handle this as well before settling on an approach. Maybe a wrapper prop (or layout as NextJS calls it) would be an alternative to fallback - trading terseness for flexibility.

Note that these don't go in options, but are props to Screen. This means it'll be handled by @react-navigation/core and not the individual navigators - that keeps the navigator's code simpler and provides a consistent implementation in all navigators. I guess there also need to be screenLoader, screenLoading and screenError on group and navigators similar to screenOptions to provide defaults.

Can you describe a bit more about your use case @xotahal - especially why do you need initialParams to be computed based on store? Whichever approach we take, the params would be initialized before the screen is finished suspending, so it won't ever be initialParams. I guess the loader could call setParams to store something in params similar to how @levibuzolic wrote. But ideally, this data should be stored using a separate cache. It doesn't fit with my mental model of params and options.

After I thought a bit more, I think not suspending UI outside the screens such as header and tab bar is probably not a big deal. For tabs, they need to be displayed regardless of whether the screen has loaded or not. Stack header can be hidden until there's data.

One reason I'm hesitant about a wrapper prop is that recently I've been thinking of adding a layout prop to navigators. It's essentially a wrapper that'll wrap the navigator's content, however, the main difference is that it'd have access to the navigator's navigation context (such as state, etc.). Currently, it's not possible at all - you can only wrap the navigator but it won't have access to the navigator's context.

This prop would enable a lot of flexibility that was not possible before, such as adding persistent UI elements:

• Add a floating footer similar to floating header to stack screens
• Add a sidebar in bottom tab navigator, or a tab bar in drawer navigator

If the navigator has this prop, having a very similar prop for screens would be confusing, especially when both do very different yet similar things.

[jetaggart]

I would love to be able to have a built in solution to wrap screens. I'm doing something similar to the HOC suggestion above.

FWIW, it may be worth addressing the current state of this in the docs somewhere. It seems like native-stack is swallowing suspending components. I got really hung up trying to figure out why some suspending screens would just show a blank screen instead of throwing an unhandled suspense error since I had no suspense boundaries in place. I believe it has to do with react-native-screens internally using react-freeze which creates a suspense boundary deep in the native navigation stack. It'd be nice to at least get a a console warning or error.

[MaxAst]

The three proposed props per screen sound great! I'm currently working with relay and I took the "Manually wrapping" approach mentioned by @levibuzolic, which is a bit painful.

[bndkt]

I'm in the same situation as @MaxAst , trying to make React Navigation work with Relay. The main obstacle is passing loaded data from the Navigator to the Screen. I've scribbled together a visualization of how the render-as-you-fetch pattern works with Relay and how it maps (or fails to map) to React Navigation to give you some background.

From what I've understood from @satya164 's post, the three proposed props could solve all three challenges described in my graphic, assuming that the loader is fired upon a navigation event (and can therefore execute Relay's loadQuery() and can then pass data (in this case Relay's non-serializable queryReference) to the screen component.

[MaxAst]

this perfectly illustrates the issue, thanks for sharing! @bndkt

[MaxAst]

@satya164 regarding lack of time, is there any way non-maintainers can support you with this?

[satya164]

@MaxAst sure, it'd be useful to have a summary of how it works with frameworks such as Remix and NextJS 13, the use cases they solve/any potential issues, etc.

[MaxAst]

One relevant source I found in the react docs: https://beta.reactjs.org/reference/react/useTransition#building-a-suspense-enabled-router

Regarding Remix and NextJS 13: AFAIK they do data fetching on the server by default, so I'm not sure how relevant their implementations are for react-navigation, unless the plan is to also integrate react server components into react-navigation (@EvanBacon recently shared a demo integrating react server components with expo)

[tslater]

@EvanBacon First off, ExpoRouter is amazing. So excited for v2.

I'd like to add a comment here that I think much of the React community really doesn't understand the full benefits and motivations all of the hard work Meta has been investing in React in terms of the suspense API. There's really a lot of potential to decrease loading times and give the developer control over the perceived loading time. Really, most of the large changes to React have bene built around Suspense (with the Relay framework they mention above being the flagship use-case).

A modern react-focused router should absolutely be suspense compatible. This is this biggest omission of React Navigation. I wonder if really it needs to be added there first?

You can see all the references to suspense-integrated routing in the react docs here:
https://react.dev/reference/react/Suspense

[satya164]

React Navigation 7 will have layout and screenLayout props to provide wrappers #11741

[DigitalZebra]

This is amazing news!!