React-native-navigation: [Question] showOverlay vs showModal use cases

[eightyfive]

Hi,

Just wondering if the documentation could be more specific about the different use cases of using Overlay vs Modal.

Since you could implement a Modal inside an Overlay... I feel like they overlap a lot in functionality.

But I may be wrong, can you clarify please?

---

Environment

• React Native Navigation version: ^2.4.0
• React Native version: ^0.57.8

[stella-yc]

^ I was just about to ask the same thing! There is no information in the docs related to when to use one over the other. It seems like they could be used for many similar purposes, but it is not clear what the limits of functionality are of one over the other.

[stokesbga]

@eightyfive @stella-yc

In RNN, modals are essentially screens that are pushed onto the stack of a single parent screen, while overlays can be render partial screen components over a transparent background. Something like a message popup/custom alert would be an example of an overlay, and a modal would be a sub-activity screen that aids/extends the functionality of the parent screen when it wouldn't make sense to add it directly to the parent screen.

Generally, fundamental UX rules state that you should have ONE purpose/task per screen.

[eightyfive]

In RNN, modals are essentially screens that are pushed onto the stack of a single parent screen

Hmmm, that would mean that show/dismissModal(componentID) is essentially the same as push/popScreen(componentID) 🤔

But as far as I understand, a modal is not the current stack, because it cannot be "popped" with the same unified API popScreen, but only with dismissModal API.

So it's like having 2 APIs to describe the same thing (if screens and modals live in the same stack).

Just highlighting the confusion.

What you're saying would be best described as (IMHO !):

pushScreen({
  component: {
    name: 'myModal',
    options: {
      asModal: true
    }
  }
})

So showModal seems to be essentially that... A "way to push a screen as Modal" (if they live in the same stack...).

From playing around with the API, here are my random observations (my 2 cents):

• Showing an overlay "full screen" kinda defeats the purpose (You want some transparent background here)
• Modal have a sliding up animation by default (Android...)
• Modal is essentially a new screen displayed as a modal (as highlighted by @stokesbga)
• Modal is just an alternative way to push a screen
• Overlays should not slide up the same way modal do...

Examples of overlay use:

• Onboarding overlays
• Alerts (although one could use the official Alert for that...)
• "Anything on top of everything with a transparent background and covering only part of the screen"

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.
If you believe the issue is still relevant, please test on the latest Detox and report back. Thank you for your contributions.

[eightyfive]

The fundamental difference between the two APIs is that showModal is called from a Screen, while showOverlay can only be called from the Top Level object.

So while you could use the two to achieve the same thing, this should give you an indication of when to use one or the other:

• showModal for pushing new stack of screens extending one screen functionality
• showOverlay for overall, Screen-unrelated, app wide pieces of UI displaying on top of everything (ex: toaster)