Managing Android Fragment Back Stack with the FragmentOperator Library

Android introduced Fragment support in API Level 11 (Android 3.0) to enable more dynamic UI on large screens such as tablets. Because fragment usage and the default back‑stack behavior can become complex, especially when custom back‑stack handling is required, Tubi created the open‑source FragmentOperator library to simplify these tasks, demonstrated with Kotlin code.

Google recommends using FragmentTransaction for fragment operations, adding each transaction to the back stack. By assigning a tag to a fragment when it is added, developers can later retrieve the fragment with findFragmentByTag and control the order of back‑stack entries.

Example of adding a fragment with a tag:

fragmentTransaction.replace(containerId, fragment, fragmentTag)

Marking a transaction to be added to the back stack with the same tag: fragmentTransaction.addToBackStack(fragmentTag) In the FragmentOperator codebase, fragments and their transactions share the same tag, ensuring each fragment instance has a unique identifier that can be managed consistently throughout the back stack.

A typical use case is an e‑commerce app with a guest mode where the navigation flow is HomeFragment → AuthFragment → DetailFragment. After a successful login, the AuthFragment should be skipped when the user presses back, returning directly to HomeFragment.

This can be achieved by using the Android method popBackStack(String name, int flags) to pop to a specific tag, effectively skipping the unwanted fragment.

FragmentOperator stores two variables in BaseFragment: previousFragmentTag, which indicates the fragment to display after a pop, and skipOnPop, a flag that determines whether the current fragment should be omitted from the back‑stack pop operation.

To guarantee that only one instance of a fragment exists in the back stack, FragmentOperator provides the @SingleInstanceFragment annotation. For example:

@SingleInstanceFragment
public class SignUpFragment {}

When a new fragment is loaded, FragmentOperator checks for this annotation; if present, it removes any existing instance of that fragment from the stack before adding the new one, preventing duplicate pages and keeping navigation tidy.

Overall, the FragmentOperator library consolidates fragment‑related functionality—tagging, custom back‑stack ordering, skipping, and single‑instance enforcement—into a reusable component that simplifies Android navigation management for developers.