Clarify or expose Android Activity lifecycle separately from AppState background

[federicobartoli]

Summary

React Native currently exposes Android AppState in a way that can make
Activity.onPause() indistinguishable from a real app background transition.

This is documented behavior today, but it can be surprising in Android system
flows such as autofill credential pickers and password managers.

Context

On Android, AppState background can be emitted when another Activity takes
focus, including temporary system activities such as autofill credential pickers.

This behavior was recently clarified in:

• Clarify Android AppState background for autofill credential pickers react/react-native-website#5079
• Clarify Android AppState background API docs react/react-native#56779

A related historical issue is:

• [Android] pressing soft keyboard suggestion from autofill with Google triggers AppState react/react-native#36420

Problem

For many app developers, AppState background -> active is treated as "the
user left the app and returned". Apps often use this transition to refetch data,
refresh auth state, or reset screens.

However, Android may pause the host Activity for temporary system flows where
the app is still visually part of the user flow. One concrete example is:

1. A login screen has username/password TextInputs with Android autofill
   enabled.
2. The user taps a saved credential from Google Password Manager / Autofill.
3. React Native emits AppState active -> background -> active.
4. App code listening for active refetches data and remounts the login form.
5. Android loses the autofill target before credentials are filled.

The app can avoid this by not doing destructive work on every active event, but
the underlying API still collapses several Android lifecycle concepts into one
state.

Question / Proposal

Should React Native expose a more precise Android lifecycle signal, separate from
AppState?

Possible directions:

• Keep AppState behavior unchanged, but expose an Android-only Activity/host
  lifecycle event such as resumed, paused, and possibly stopped.
• Add a separate API, for example ActivityState, for apps that need Android
  Activity lifecycle semantics.
• Reconsider whether Android AppState.background should be based on a lifecycle
  signal closer to "not visible" rather than "paused", while accounting for
  backwards compatibility.
• Keep the current API and rely only on documentation.

The goal is not to special-case autofill or password managers. The broader issue
is that Android Activity pause and "app truly backgrounded" are different
concepts, but React Native currently exposes them through the same high-level
AppState transition.

Why this matters

A more precise signal would let apps distinguish:

• user actually left the app;
• temporary Android system UI / credential picker / permission flow;
• loss of focus;
• Activity pause without the same product meaning as a full app background.

This would help apps avoid fragile heuristics around AppState while preserving
the existing documented behavior for current users.

Contribution

If maintainers think one of these directions is appropriate, I would be happy to
help prototype and submit the implementation.

[federicobartoli]

Hi @huntie , sorry for the direct ping.

You reviewed the related in-package docs PR (facebook/react-native#56779), so I wanted to ask whether this proposal is in the right place and whether you think this is worth exploring further.

The docs clarification helped make the current Android behavior explicit, but the open question here is whether React Native should expose a separate Android Activity/host lifecycle signal, or whether maintainers would prefer keeping the current AppState semantics and treating this as docs-only.

No pressure at all; I’m mainly looking for direction before spending more time on a prototype. Happy to help if there’s appetite for it.

[huntie]

Got it. cc @cortinico for Android API decisions.

Note that we're pretty busy internally right now so might not look at this soon pr🙏🏻

[cortinico]

Hey @federicobartoli
I believe this has been discussed in the past to some extent here:

• Enhanced lifecycle-aware module registry #849

Keep AppState behavior unchanged, but expose an Android-only Activity/host
lifecycle event such as resumed, paused, and possibly stopped.

This would probably be the 'preferred' solution for me. However it creates an asymmetry between Android & iOS that we try to avoid in general.

Add a separate API, for example ActivityState, for apps that need Android
Activity lifecycle semantics.

For Expo apps, you could use this API to achieve what you're looking for:
https://docs.expo.dev/modules/android-lifecycle-listeners/

Reconsider whether Android AppState.background should be based on a lifecycle
signal closer to "not visible" rather than "paused", while accounting for
backwards compatibility.

This is going to be major breaking change, and we'll break a bunch of existing behaviors if we change this.

Keep the current API and rely only on documentation.

That's essentially what we're doing.

In principle I agree, we should move #849 forward and effectively upstream Expo's API inside react-native core, but we haven't had the bandwidth to do so.

[federicobartoli]

Thanks @cortinico , this is really helpful.

I read through #849, and I agree it looks like the right architectural place for this problem. The AppState/autofill case seems like a concrete symptom of the broader lifecycle gap, rather than something that should be fixed by changing AppState itself.

I also agree that changing Android AppState.background semantics would be too risky from a backwards-compatibility perspective.

There are clearly some tricky design constraints there, especially around startup cost, brownfield integration, and keeping the API shape sensible across platforms.

Would it be useful if I took a first pass at studying the existing proposal and putting together a small architectural follow-up that connects the AppState/autofill case to #849, using Expo’s Android lifecycle listener API as a reference?

I wouldn’t want to jump straight into an implementation before there’s alignment on the shape of the API, but I’d be happy to help move the discussion forward in a concrete way.

[cortinico]

Would it be useful if I took a first pass at studying the existing proposal and putting together a small architectural follow-up that connects the AppState/autofill case to #849, using Expo’s Android lifecycle listener API as a reference?

Totally!

It would be great to also have @matinzd or someone else from Expo involved in the conversation here.