React-Navigation Stack Navigator with Horizontal Modals

React-Navigation is the most popular routing and navigation framework for React Native apps. It’s easy to implement and offers many navigation capabilities like stack-navigators, drawers, and deep linking through paths from the get-go.

The stack-navigator includes what you need for stacking react-native screen on top of each other and navigating between them: https://reactnavigation.org/docs/en/stack-navigator.html

Stack-navigators mode property defaults to “card”, but when set to “modal” adjusts the workings of react-navigation to keep screens behind the currently active screen loaded. By using a stack-navigator in modal mode, you can create nice semi- or fully opaque backgrounds: show the main screen behind the currently active screen. This is great for screens that look like card stacks and screens with a translucent, semi-transparent background. Check out these two examples from Places Rocks:

example of 2 modal stacks: cards carousel and chat with translucent background

Achieving any stacked modal behavior in react-navigation is relatively easy once you know how react-navigation’s stack-navigator works.

A simple modal stack-navigator with a transparent background and without the standard iOS/Android headers can be initialized by calling cardStackNavigator() like this:

simple react-navigation stack-navigator

Check out this gif of a 3-screen example expo app using the simple stack-navigator coded above. We have the HomeScreen with options to navigate to Links and Settings. And both Links and Settings have a translucent background and are animated like a standard iOS modal.

vertical react-navigation modal stacks

React-Navigation’s stack-navigator pushes models on top by using the standard iOS modal behavior. This looks great for normal modals, but we have two screens here: Links and Settings. Both coming in from the bottom is not optimal. We want Links to come in from the right and Settings come in from the left side, including swiping the modals away from the right/left side of the screen to get back to Home.

There are two parts to making the modals slide in from the right/left side of the screen:

1. gestureDirection determines which gestures the user can use to swipe-away the active modal.
2. `cardStyleInterpolator` determines how the modal will be animated on open and close.

Let’s look atgestureDirection first. React-Navigation offers four options for gestureDirection: horizontal, horizontal-inverted, vertical, vertical-inverted. ‘horizontal’ gesture closes by sliding to the right. ‘horizontal-inverted’ gesture closes by sliding to the left. Check out the docs for more detail here: https://reactnavigation.org/docs/en/stack-navigator.html#animation-related-options

Using gestureDirection: "horizontal" for LinksScreen and gestureDirection: "horizontal-inverted" for SettingsScreen will allow the user to swipe-away LinksScreen and SettingsScreen horizontally to the right/left respectively. But without updating cardStyleInterpolator the modals will still animate up vertically from the bottom of the screen.

Next up is our custom for horizontal modals cardStyleInterpolator. Checking out the docs again, we can see that there are five cardStyleInterpolators implemented by react-navigation for us to use: https://reactnavigation.org/docs/en/stack-navigator.html#cardstyleinterpolators. These five pre-implemented cardStyleInterpolators imitate standard Android and iOS behavior and should be used for this goal. We will implement a deviation of the CardStyleInterpolators.forHorizontalIOS specifically for modals, where the last screen should not move. Let’s call it forHorizontalModal cardStyleInterpolator:

CardStyleInterpolators.forHorizontalModal

React-Navigation’s CardStyleInterpolators are functions that act as definitions for styles needed for the card transition by using react-native’s Animated API.

Now, the only thing left is to apply the applicable horizontal gestureDirection and the forHorizontalModal cardStyleInterpolator to both the Links- and SettingsScreen:

We’re done! Check out the react-navigation stack-navigator with horizontal modal and translucent backgrounds in action here:

horizontal react-navigation modal stacks

Build some nice navigation flows with this knowledge and share them with the community! 👩‍💻🧑‍💻👨‍💻

Thanks for Reading 👏

Check out the example expo project in this GitHub repo: https://github.com/abegehr/react-navigation-horizontal-modal-stack

Thanks, to react-navigation for making navigating react-native apps a breeze!

Stay tuned for more articles and leave a high-five ✋