| **Note:** We strongly recommend using the [Navigation library](https://developer.android.com/guide/navigation) to manage your app's navigation. The framework follows best practices for working with fragments, the back stack, and the fragment manager. For more information about Navigation, see [Get started with the Navigation component](https://developer.android.com/guide/navigation/navigation-getting-started) and [Migrate to the Navigation component](https://developer.android.com/guide/navigation/navigation-migrate).

[`FragmentManager`](https://developer.android.com/reference/androidx/fragment/app/FragmentManager) is
the class responsible for performing actions on your app's fragments, such
as adding, removing, or replacing them and adding them to the back stack.

You might never interact with `FragmentManager` directly if you're using
the [Jetpack Navigation](https://developer.android.com/guide/navigation) library, as it works with the
`FragmentManager` on your behalf. However, any app using fragments is
using `FragmentManager` at some level, so it's important to understand what
it is and how it works.

This page covers:

- How to access the `FragmentManager`.
- The role of `FragmentManager` in relation to your activities and fragments.
- How to manage the back stack with `FragmentManager`.
- How to provide data and dependencies to your fragments.

## Access the FragmentManager

You can access the `FragmentManager` from an activity or from a fragment.

[`FragmentActivity`](https://developer.android.com/reference/androidx/fragment/app/FragmentActivity)
and its subclasses, such as
[`AppCompatActivity`](https://developer.android.com/reference/androidx/appcompat/app/AppCompatActivity),
have access to the `FragmentManager` through the
[`getSupportFragmentManager()`](https://developer.android.com/reference/androidx/fragment/app/FragmentActivity#getSupportFragmentManager())
method.

Fragments can host one or more child fragments. Inside
a fragment, you can get a reference to the `FragmentManager` that manages
the fragment's children through
[`getChildFragmentManager()`](https://developer.android.com/reference/androidx/fragment/app/Fragment#getChildFragmentManager()).
If you need to access its host `FragmentManager`, you can use
[`getParentFragmentManager()`](https://developer.android.com/reference/androidx/fragment/app/Fragment#getParentFragmentManager()).

Here are a couple of examples to see the relationships between
fragments, their hosts, and the `FragmentManager` instances associated
with each.
![two ui layout examples showing the relationships between
fragments and their host activities](https://developer.android.com/static/images/guide/fragments/fragment-host.png) **Figure 1.** Two UI layout examples showing the relationships between fragments and their host activities.

Figure 1 shows two examples, each of which has a single activity host. The
host activity in both of these examples displays top-level navigation to
the user as a
[`BottomNavigationView`](https://developer.android.com/reference/com/google/android/material/bottomnavigation/BottomNavigationView)
that is responsible for swapping out the host fragment with different
screens in the app. Each screen is implemented as a separate fragment.

The host fragment in Example 1 hosts two child fragments that
make up a split-view screen. The host fragment in Example 2 hosts a
single child fragment that makes up the display fragment of a
[swipe view](https://developer.android.com/guide/navigation/navigation-swipe-view-2#implement_swipe_views).

Given this setup, you can think about each host as having a `FragmentManager`
associated with it that manages its child fragments. This is illustrated in
figure 2 along with property mappings between `supportFragmentManager`,
`parentFragmentManager`, and `childFragmentManager`.
![each host has its own FragmentManager associated with it
that manages its child fragments](https://developer.android.com/static/images/guide/fragments/manager-mappings.png) **Figure 2.** Each host has its own `FragmentManager` associated with it that manages its child fragments.

The appropriate `FragmentManager` property to reference depends on where
the callsite is in the fragment hierarchy along with which fragment manager
you are trying to access.

Once you have a reference to the `FragmentManager`, you can use it to
manipulate the fragments being displayed to the user.

### Child fragments

Generally speaking, your app consists of a single or small number
of activities in your application project, with each activity representing
a group of related screens. The activity might provide a point to place
top-level navigation and a place to scope `ViewModel` objects and other view-state
between fragments. A fragment represents an individual destination in your
app.

If you want to show multiple fragments at once, such as in a split-view
or a dashboard, you can use child fragments that are managed by your
destination fragment and its child fragment manager.

Other use cases for child fragments are the following:

- [Screen slides](https://developer.android.com/training/animation/screen-slide-2), using a `ViewPager2` in a parent fragment to manage a series of child fragment views.
- Sub-navigation within a set of related screens.
- Jetpack Navigation uses child fragments as individual destinations. An activity hosts a single parent `NavHostFragment` and fills its space with different child destination fragments as users navigate through your app.

## Use the FragmentManager

The `FragmentManager` manages the fragment back stack. At runtime, the
`FragmentManager` can perform back stack operations like adding or removing
fragments in response to user interactions. Each set of changes is
committed together as a single unit called a
[`FragmentTransaction`](https://developer.android.com/reference/androidx/fragment/app/FragmentTransaction).
For a more in-depth discussion about fragment transactions, see the
[fragment transactions guide](https://developer.android.com/guide/fragments/transactions).

When the user taps the Back button on their device, or when you call
[`FragmentManager.popBackStack()`](https://developer.android.com/reference/androidx/fragment/app/FragmentManager#popBackStack()),
the top-most fragment transaction pops off of the stack. If there are no more fragment
transactions on the stack, and if you aren't using child fragments, the Back
event bubbles up to the activity. If you *are* using child fragments, see
[special considerations for child and sibling fragments](https://developer.android.com/guide/fragments/fragmentmanager#considerations).

When you call
[`addToBackStack()`](https://developer.android.com/reference/androidx/fragment/app/FragmentTransaction#addToBackStack(java.lang.String))
on a transaction, the transaction can include any number of
operations, such as adding multiple fragments or replacing fragments in multiple
containers.

When the back stack is popped, all these
operations reverse as a single atomic action. However, if you committed
additional transactions prior to the `popBackStack()` call, and if you
*didn't* use `addToBackStack()` for the transaction, these operations
*don't* reverse. Therefore, within a single `FragmentTransaction`, avoid
interleaving transactions that affect the back stack with those that don't.

## Perform a transaction

To display a fragment within a layout container, use the `FragmentManager`
to create a `FragmentTransaction`. Within the transaction, you can then
perform an
[`add()`](https://developer.android.com/reference/androidx/fragment/app/FragmentTransaction#add(int,%20java.lang.Class%3C?%20extends%20androidx.fragment.app.Fragment%3E,%20android.os.Bundle))
or [`replace()`](https://developer.android.com/reference/androidx/fragment/app/FragmentTransaction#replace(int,%20java.lang.Class%3C?%20extends%20androidx.fragment.app.Fragment%3E,%20android.os.Bundle))
operation on the container.

For example, a simple `FragmentTransaction` might look like this:  

### Kotlin

```kotlin
supportFragmentManager.commit {
   replace<ExampleFragment>(R.id.fragment_container)
   setReorderingAllowed(true)
   addToBackStack("name") // Name can be null
}
```

### Java

```java
FragmentManager fragmentManager = getSupportFragmentManager();
fragmentManager.beginTransaction()
    .replace(R.id.fragment_container, ExampleFragment.class, null)
    .setReorderingAllowed(true)
    .addToBackStack("name") // Name can be null
    .commit();
```

In this example, `ExampleFragment` replaces the fragment, if any, that is
currently in the layout container identified by the
`R.id.fragment_container` ID. Providing the fragment's class to the
[`replace()`](https://developer.android.com/reference/androidx/fragment/app/FragmentTransaction#replace(int,%20java.lang.Class%3C?%20extends%20androidx.fragment.app.Fragment%3E,%20android.os.Bundle))
method lets the `FragmentManager` handle instantiation using its
[`FragmentFactory`](https://developer.android.com/reference/androidx/fragment/app/FragmentFactory).
For more information, see the [Provide dependencies to your fragments](https://developer.android.com/guide/fragments/fragmentmanager#dependencies)
section.

[`setReorderingAllowed(true)`](https://developer.android.com/reference/androidx/fragment/app/FragmentTransaction#setReorderingAllowed(boolean))
optimizes the state changes of the fragments involved in the transaction
so that animations and transitions work correctly. For more information on
navigating with animations and transitions, see
[Fragment transactions](https://developer.android.com/guide/fragments/transactions) and
[Navigate between fragments using animations](https://developer.android.com/training/basics/fragments/animate).

Calling
[`addToBackStack()`](https://developer.android.com/reference/androidx/fragment/app/FragmentTransaction#addToBackStack(java.lang.String))
commits the transaction to the back stack. The user can later reverse the
transaction and bring back the previous fragment by tapping the Back
button. If you added or removed multiple fragments within a single
transaction, all those operations are undone when the back stack
is popped. The optional name provided in the `addToBackStack()` call gives
you the ability to pop back to a specific transaction using
[`popBackStack()`](https://developer.android.com/reference/androidx/fragment/app/FragmentManager#popBackStack(java.lang.String,%20int)).

If you don't call `addToBackStack()` when you perform a transaction that
removes a fragment, then the removed fragment is destroyed when the
transaction is committed, and the user cannot navigate back to it. If you
do call `addToBackStack()` when removing a fragment, then the fragment is
only `STOPPED` and is later `RESUMED` when the user navigates back. Its view
*is* destroyed in this case. For more information, see
[Fragment lifecycle](https://developer.android.com/guide/fragments/lifecycle).

### Find an existing fragment

You can get a reference to the current fragment within a layout container
by using
[`findFragmentById()`](https://developer.android.com/reference/androidx/fragment/app/FragmentManager#findFragmentById(int)).
Use `findFragmentById()` to look up a fragment either by the given ID when
inflated from XML or by the container ID when added in a
`FragmentTransaction`. Here's an example:  

### Kotlin

```kotlin
supportFragmentManager.commit {
   replace<ExampleFragment>(R.id.fragment_container)
   setReorderingAllowed(true)
   addToBackStack(null)
}
...
val fragment: ExampleFragment =
        supportFragmentManager.findFragmentById(R.id.fragment_container) as ExampleFragment
```

### Java

```java
FragmentManager fragmentManager = getSupportFragmentManager();
fragmentManager.beginTransaction()
    .replace(R.id.fragment_container, ExampleFragment.class, null)
    .setReorderingAllowed(true)
    .addToBackStack(null)
    .commit();
...
ExampleFragment fragment =
        (ExampleFragment) fragmentManager.findFragmentById(R.id.fragment_container);
```

Alternatively, you can assign a unique tag to a fragment and get a
reference using
[`findFragmentByTag()`](https://developer.android.com/reference/androidx/fragment/app/FragmentManager#findFragmentByTag(java.lang.String)).
You can assign a tag using the `android:tag` XML attribute on fragments that
are defined within your layout or during an `add()` or `replace()`
operation within a `FragmentTransaction`.  

### Kotlin

```kotlin
supportFragmentManager.commit {
   replace<ExampleFragment>(R.id.fragment_container, "tag")
   setReorderingAllowed(true)
   addToBackStack(null)
}
...
val fragment: ExampleFragment =
        supportFragmentManager.findFragmentByTag("tag") as ExampleFragment
```

### Java

```java
FragmentManager fragmentManager = getSupportFragmentManager();
fragmentManager.beginTransaction()
    .replace(R.id.fragment_container, ExampleFragment.class, null, "tag")
    .setReorderingAllowed(true)
    .addToBackStack(null)
    .commit();
...
ExampleFragment fragment = (ExampleFragment) fragmentManager.findFragmentByTag("tag");
```

### Special considerations for child and sibling fragments

Only one `FragmentManager` can control the fragment back stack
at any given time. If your app shows multiple sibling fragments on the
screen at the same time, or if your app uses child fragments, then one
`FragmentManager` is designated to handle your app's primary navigation.

To define the primary navigation fragment inside of a fragment transaction,
call the
[`setPrimaryNavigationFragment()`](https://developer.android.com/reference/kotlin/androidx/fragment/app/FragmentTransaction#setPrimaryNavigationFragment(androidx.fragment.app.Fragment))
method on the transaction, passing in the instance of the fragment whose
`childFragmentManager` has primary control.

Consider the navigation structure as a series of layers, with the activity
as the outermost layer, wrapping each layer of child fragments underneath.
Each layer has a single primary navigation fragment.

When the Back
event occurs, the innermost layer controls navigation behavior. Once the
innermost layer has no more fragment transactions from which to pop back,
control returns to the next layer out, and this process repeats until you
reach the activity.

When two or more fragments are displayed at the same time, only
one of them is the primary navigation fragment. Setting a fragment
as the primary navigation fragment removes the designation from the previous
fragment. Using the preceding example, if you set the detail fragment as the
primary navigation fragment, the main fragment's designation is removed.

## Support multiple back stacks

In some cases, your app might need to support multiple back stacks. A common
example is if your app uses a bottom navigation bar. `FragmentManager` lets
you support multiple back stacks with the `saveBackStack()` and
`restoreBackStack()` methods. These methods let you swap between back
stacks by saving one back stack and restoring a different one.
| **Note:** Alternatively, you can use the [`NavigationUI`](https://developer.android.com/reference/androidx/navigation/ui/NavigationUI) component, which automatically handles multiple back stack support for [bottom
| navigation](https://developer.android.com/guide/navigation/navigation-ui#bottom_navigation).

`saveBackStack()` works similarly to calling `popBackStack()` with the optional
`name` parameter: the specified transaction and all transactions after it on the
stack are popped. The difference is that `saveBackStack()` [saves the
state](https://developer.android.com/guide/fragments/saving-state) of all fragments in the popped
transactions.

For example, suppose you previously added a fragment to the back stack by
committing a `FragmentTransaction` using `addToBackStack()`, as shown in the
following example:  

### Kotlin

```kotlin
supportFragmentManager.commit {
  replace<ExampleFragment>(R.id.fragment_container)
  setReorderingAllowed(true)
  addToBackStack("replacement")
}
```

### Java

```java
supportFragmentManager.beginTransaction()
  .replace(R.id.fragment_container, ExampleFragment.class, null)
  // setReorderingAllowed(true) and the optional string argument for
  // addToBackStack() are both required if you want to use saveBackStack()
  .setReorderingAllowed(true)
  .addToBackStack("replacement")
  .commit();
```

In that case, you can save this fragment transaction and the state of
`ExampleFragment` by calling `saveBackStack()`:  

### Kotlin

```kotlin
supportFragmentManager.saveBackStack("replacement")
```

### Java

```java
supportFragmentManager.saveBackStack("replacement");
```
| **Note:** You can use `saveBackStack()` only with transactions that call `setReorderingAllowed(true)` so that the transactions can be restored as a single, atomic operation.

You can call `restoreBackStack()` with the same name parameter to restore all of
the popped transactions and all of the saved fragment states:  

### Kotlin

```kotlin
supportFragmentManager.restoreBackStack("replacement")
```

### Java

```java
supportFragmentManager.restoreBackStack("replacement");
```
| **Note:** You can't use `saveBackStack()` and `restoreBackStack()` unless you pass an optional name for your fragment transactions with `addToBackStack()`.

## Provide dependencies to your fragments

When adding a fragment, you can instantiate the fragment manually and
add it to the `FragmentTransaction`.  

### Kotlin

```kotlin
fragmentManager.commit {
    // Instantiate a new instance before adding
    val myFragment = ExampleFragment()
    add(R.id.fragment_view_container, myFragment)
    setReorderingAllowed(true)
}
```

### Java

```java
// Instantiate a new instance before adding
ExampleFragment myFragment = new ExampleFragment();
fragmentManager.beginTransaction()
    .add(R.id.fragment_view_container, myFragment)
    .setReorderingAllowed(true)
    .commit();
```

When you commit the fragment transaction, the instance of the fragment
you created is the instance used. However, during a
[configuration change](https://developer.android.com/guide/topics/resources/runtime-changes), your
activity and all of its fragments are destroyed and then recreated with
the most applicable
[Android resources](https://developer.android.com/guide/topics/resources/providing-resources#BestMatch).
The `FragmentManager` handles all of this for you: it recreates instances
of your fragments, attaches them to the host, and recreates the back stack
state.

By default, the `FragmentManager` uses a
[`FragmentFactory`](https://developer.android.com/reference/androidx/fragment/app/FragmentFactory) that
the framework provides to instantiate a new instance of your fragment. This
default factory uses reflection to find and invoke a no-argument constructor
for your fragment. This means that you can't use this default factory to
provide dependencies to your fragment. It also means that any custom
constructor you used to create your fragment the first time is *not* used
during recreation by default.

To provide dependencies to your fragment, or to use any custom
constructor, instead create a custom `FragmentFactory` subclass
and then override
[`FragmentFactory.instantiate`](https://developer.android.com/reference/androidx/fragment/app/FragmentFactory#instantiate(java.lang.ClassLoader,%20java.lang.String)).
You can then override the default factory of the `FragmentManager` with
your custom factory, which is then used to instantiate your fragments.

Suppose you have a `DessertsFragment` that is responsible for displaying
popular desserts in your hometown, and that `DessertsFragment`
has a dependency on a `DessertsRepository` class that provides it with
the information it needs to display the correct UI to your user.

You might define your `DessertsFragment` to require a `DessertsRepository`
instance in its constructor.  

### Kotlin

```kotlin
class DessertsFragment(val dessertsRepository: DessertsRepository) : Fragment() {
    ...
}
```

### Java

```java
public class DessertsFragment extends Fragment {
    private DessertsRepository dessertsRepository;

    public DessertsFragment(DessertsRepository dessertsRepository) {
        super();
        this.dessertsRepository = dessertsRepository;
    }

    // Getter omitted.

    ...
}
```

A simple implementation of your `FragmentFactory` might look similar to
the following.  

### Kotlin

```kotlin
class MyFragmentFactory(val repository: DessertsRepository) : FragmentFactory() {
    override fun instantiate(classLoader: ClassLoader, className: String): Fragment =
            when (loadFragmentClass(classLoader, className)) {
                DessertsFragment::class.java -> DessertsFragment(repository)
                else -> super.instantiate(classLoader, className)
            }
}
```

### Java

```java
public class MyFragmentFactory extends FragmentFactory {
    private DessertsRepository repository;

    public MyFragmentFactory(DessertsRepository repository) {
        super();
        this.repository = repository;
    }

    @NonNull
    @Override
    public Fragment instantiate(@NonNull ClassLoader classLoader, @NonNull String className) {
        Class<? extends Fragment> fragmentClass = loadFragmentClass(classLoader, className);
        if (fragmentClass == DessertsFragment.class) {
            return new DessertsFragment(repository);
        } else {
            return super.instantiate(classLoader, className);
        }
    }
}
```

This example subclasses `FragmentFactory`, overriding the `instantiate()`
method to provide custom fragment creation logic for a `DessertsFragment`.
Other fragment classes are handled by the default behavior of
`FragmentFactory` through `super.instantiate()`.

You can then designate `MyFragmentFactory` as the factory to use when
constructing your app's fragments by setting a property on the
`FragmentManager`. You must set this property prior to your activity's
`super.onCreate()` to ensure that `MyFragmentFactory` is used when
recreating your fragments.  

### Kotlin

```kotlin
class MealActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        supportFragmentManager.fragmentFactory = MyFragmentFactory(DessertsRepository.getInstance())
        super.onCreate(savedInstanceState)
    }
}
```

### Java

```java
public class MealActivity extends AppCompatActivity {
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        DessertsRepository repository = DessertsRepository.getInstance();
        getSupportFragmentManager().setFragmentFactory(new MyFragmentFactory(repository));
        super.onCreate(savedInstanceState);
    }
}
```

Setting the `FragmentFactory` in the activity overrides fragment
creation throughout the activity's fragment hierarchy. In other words,
the `childFragmentManager` of any child fragments you add uses the custom
fragment factory set here unless overridden at a lower level.

### Test with FragmentFactory

In a single activity architecture, test your fragments in
isolation using the
[`FragmentScenario`](https://developer.android.com/reference/androidx/fragment/app/testing/FragmentScenario)
class. Since you can't rely on the custom `onCreate` logic of your
activity, you can instead pass the `FragmentFactory` in as an argument
to your fragments test, as shown in the following example:  

```kotlin
// Inside your test
val dessertRepository = mock(DessertsRepository::class.java)
launchFragment<DessertsFragment>(factory = MyFragmentFactory(dessertRepository)).onFragment {
    // Test Fragment logic
}
```

For detailed information about this testing process and for full examples,
see [Test your fragments](https://developer.android.com/training/basics/fragments/testing).