Add support for the predictive back gesture

**Figure 1.** Mockup of the predictive back gesture look and feel on a phone

Android 13 (API level 33) introduces a predictive back gesture for Android devices such as phones, large screens, and foldables. It is part of a multi-year release; when fully implemented, this feature will let users preview the destination or other result of a back gesture before fully completing it, allowing them to decide whether to continue or stay in the current view.

For example, using a back gesture can display an animated preview of the Home screen behind your app, as presented in the mockup in figure 1. Starting with Android 13, you can test this back-to-home animation by enabling a developer option (as described on this page).

Supporting the predictive back gesture requires updating your app, using the backward compatible OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) or higher API, or using the new OnBackInvokedCallback platform API. Most apps will use the backward compatible AndroidX API.

This update provides a migration path to properly intercept back navigation, which involves replacing back interceptions from KeyEvent.KEYCODE_BACK and any classes with onBackPressed methods such as Activity and Dialog with the new system Back APIs.

Codelab and Google I/O video

In addition to using this documentation on this page, try out our codelab. It provides a common use-case implementation of a WebView handling the predictive back gesture using AndroidX Activity APIs.

You can also view our Google I/O video, which covers additional examples of implementing the AndroidX and platform APIs.

Update an app that uses default back navigation

Updating your app to support this feature is straightforward if your app doesn't implement any custom back behavior (in other words, it leaves back handling up to the system). Simply opt in to this feature as described on this page.

If your app uses Fragments or the Navigation Component, also upgrade to AndroidX Activity 1.6.0-alpha05 or higher.

Update an app that uses custom back navigation

If your app implements custom back behavior, there are different migration paths depending on whether it uses AndroidX and how it handles back navigation.

Your app uses AndroidX	How your app handles back navigation	Recommended migration path (link on this page)
Yes	AndroidX APIs	Migrate an existing AndroidX back implementation
Yes	Unsupported platform APIs	Migrate an AndroidX app containing unsupported back navigation APIs to AndroidX APIs
No	Unsupported platform APIs, able to migrate	Migrate an app that uses unsupported back navigation APIs to platform APIs
No	Unsupported platform APIs, but unable to migrate	Defer opt-in until this becomes a required feature

Migrate an AndroidX back navigation implementation

This use case is the most common (and the most recommended). It applies to new or existing apps that implement custom gesture navigation handling with OnBackPressedDispatcher, as described in Provide custom back navigation.

If your app fits into this category, follow these steps to add support for the predictive back gesture:

To ensure that APIs that are already using OnBackPressedDispatcher APIs (such as Fragments and the Navigation Component) work seamlessly with the predictive back gesture, upgrade to AndroidX Activity 1.6.0-alpha05.
```
// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"
```
Opt in to the predictive back gesture, as described on this page.

Migrate an AndroidX app containing unsupported back navigation APIs to AndroidX APIs

If your app uses AndroidX libraries but implements or makes reference to the unsupported back navigation APIs, you’ll need to migrate to using AndroidX APIs to support the new behavior.

To migrate unsupported APIs to AndroidX APIs:

Migrate your system Back handling logic to AndroidX’s OnBackPressedDispatcher with an implementation of OnBackPressedCallback. For detailed guidance, see Provide custom back navigation.
Disable the OnBackPressedCallback when ready to stop intercepting the back gesture.
Stop intercepting back events via OnBackPressed or KeyEvent.KEYCODE_BACK.

Make sure to upgrade to AndroidX Activity 1.6.0-alpha05.

// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"

When you have successfully migrated your app, opt in to the predictive back gesture (as described on this page) to see the back-to-home system animation.

Note: OnBackPressedCallback is always called regardless of the value of android:enableOnBackInvokedCallback. In other words, disabling the system animation doesn't affect your app's back handling logic if it uses OnBackPressedCallback.

Migrate an app that uses unsupported back navigation APIs to platform APIs

If your app cannot use AndroidX libraries and instead implements or makes reference to custom Back navigation using the unsupported APIs, you must migrate to the OnBackInvokedCallback platform API.

Complete the following steps to migrate unsupported APIs to the platform API:

Use the new OnBackInvokedCallback API on devices running Android 13 or higher, and rely on the unsupported APIs on devices running Android 12 or lower.
Register your custom back logic in OnBackInvokedCallback with onBackInvokedDispatcher. This prevents the current activity from being finished, and your callback gets a chance to react to the Back action once the user completes the system Back navigation.

Unregister the OnBackInvokedCallback when ready to stop intercepting the back gesture. Otherwise, users may see undesirable behavior when using a system Back navigation—for example, "getting stuck" between views and forcing them to force quit your app.

Here’s an example of how to migrate logic out of onBackPressed:

Kotlin

@Override
fun onCreate() {
    if (BuildCompat.isAtLeastT()) {
        onBackInvokedDispatcher.registerOnBackInvokedCallback(
            OnBackInvokedDispatcher.PRIORITY_DEFAULT
        ) {
            /**
             * onBackPressed logic goes here. For instance:
             * Prevents closing the app to go home screen when in the
             * middle of entering data to a form
             * or from accidentally leaving a fragment with a WebView in it
             *
             * Unregistering the callback to stop intercepting the back gesture:
             * When the user transitions to the topmost screen (activity, fragment)
             * in the BackStack, unregister the callback by using
             * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
             * (https://developer.android.com/reference/kotlin/android/window/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
             */
        }
    }
}

Java

@Override
void onCreate() {
  if (BuildCompat.isAtLeastT()) {
    getOnBackInvokedDispatcher().registerOnBackInvokedCallback(
        OnBackInvokedDispatcher.PRIORITY_DEFAULT,
        () -> {
          /**
           * onBackPressed logic goes here - For instance:
           * Prevents closing the app to go home screen when in the
           * middle of entering data to a form
           * or from accidentally leaving a fragment with a WebView in it
           *
           * Unregistering the callback to stop intercepting the back gesture:
           * When the user transitions to the topmost screen (activity, fragment)
           * in the BackStack, unregister the callback by using
           * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
           * (https://developer.android.com/reference/kotlin/android/view/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
           */
        }
    );
  }
}

Stop intercepting back events via OnBackPressed or KeyEvent.KEYCODE_BACK for Android 13 and above.
When you have successfully migrated your app, opt in to the predictive back gesture (as described on this page) so that OnBackInvokedCallback takes effect.

Opt in to the predictive back gesture

Once you've determined how to update your app based on your case, it's easy to opt in to supporting the predictive back gesture.

To opt in, in AndroidManifest.xml, in the <application> tag, set the android:enableOnBackInvokedCallback flag to true.

<application
    ...
    android:enableOnBackInvokedCallback="true"
    ... >
...
</application>

If you don't provide a value, it defaults to false and does the following:

Disables the predictive back gesture system animation.
Ignores OnBackInvokedCallback, but OnBackPressedCallback calls continue to work.

Callback best practices

Here are best practices for using the supported system back callbacks; BackHandler (for Compose), OnBackPressedCallback, or OnBackInvokedCallback.

Determine the UI State that enables and disables each callback

UI state is a property that describes the UI. We recommend following these high-level steps.

Determine the UI state that enables and disables each callback.
Define that state using an observable data holder type, such as StateFlow or Compose State, and enable or disable the callback as the state changes.

If your app was previously associating back logic with conditional statements, this might signify you are reacting to the back event after it has already occurred—a pattern you should avoid with newer callbacks. If possible, move the callback outside of the conditional statement and instead associate the callback to an observable data holder type.

Use system back callbacks for UI Logic

UI logic dictates how to display UI. Use system back callbacks to run UI logic, such as displaying a pop-up or running an animation.

If your app enables a system back callback, the predictive animations don't run and you must handle the back event. Don't create callbacks only to run non-UI logic.

For example, if you're intercepting back events only to log, log within the Activity or Fragment lifecycle instead.

For activity-to-activity cases or fragment-to-activity cases, log if isFinishing within onDestroy is true within the Activity lifecycle.
For fragment-to-fragment cases, log if isRemoving within onDestroy is true within the Fragment's view lifecycle; or, log using onBackStackChangeStarted or onBackStackChangeCommitted methods within FragmentManager.OnBackStackChangedListener.

Create single responsibility callbacks

This is possible because you can add multiple callbacks to the dispatcher. The callbacks are added to a stack in which the last added enabled callback handles the next back gesture with one callback per back gesture.

Test the predictive back gesture animation

Starting with the Android 13 final release, you should be able to enable a developer option to test the back-to-home animation shown in figure 1.

To test this animation, complete the following steps:

On your device, go to Settings > System > Developer options.
Select Predictive back animations.
Launch your updated app, and use the back gesture to see it in action.