Dialog destinations

This document outlines how the use of dialog destinations can introduce unique considerations for how you need to manage your back stack.

Overview

Dialog destinations implement the FloatingWindow interface. As such, they overlay other destinations on the back stack.

One or more FloatingWindow destinations can only exist on the top of the back stack. This is because when the user navigates to a destination that does not implement FloatingWindow, the NavController automatically pops all FloatingWindow destinations off the top of the stack. This ensures that the current destination is always fully visible above other destinations on the back stack.

Example

As an example, if the back stack consists solely of non-floating destinations, and the user navigates to a Dialog destination, then the back stack might look similar to figure 2:

a back stack with a dialog destination on top
Figure 2. A back stack with a Dialog destination on top.

If the user then navigates to another Dialog destination, it is then added to the top of the back stack, as shown in figure 3:

a back stack with two dialog destinations on top
Figure 3. A back stack with two Dialog destinations on top.

If the user then navigates to a non-floating destination, any FloatingWindow destinations are first popped from the top of the back stack before navigating to the new destination, as shown in figure 4:

the dialog destinations are popped, and the new destination
            is added
Figure 4. The Dialog destinations are popped, and the new destination is added.