AppState

AppState is the core API for knowing whether your app is in the foreground. AppState.currentState holds the current value, and a change listener fires on every transition.

The states you will see:

• active — in the foreground and receiving input.
• background — the user switched away, went home or locked the phone.
• inactive — iOS only, a brief in-between state: pulling down Notification Centre, the app switcher, an incoming call, a system permission dialog.

useEffect(() => {
  const sub = AppState.addEventListener('change', (next) => {
    if (next === 'active') refreshData();
  });
  return () => sub.remove();
}, []);

Typical uses are refreshing data when the user returns, pausing video or timers when they leave, locking a banking screen, or flushing analytics. Data libraries such as TanStack Query can wire AppState into their “refetch on focus” behaviour, since React Native has no browser visibilitychange event.

Common mistakes:

• Treating inactive as background. A system permission prompt makes iOS apps inactive, so logging out on inactive logs users out mid-flow. Decide which transitions you actually care about.
• Expecting code to keep running in the background. Once backgrounded, the OS may suspend the JavaScript thread within seconds; timers and pending work stop. Real background work needs the platform’s background task mechanisms.
• Forgetting cleanup. Not removing the subscription in the useEffect cleanup leaks listeners every time the component remounts.

AppState describes the whole app, not one screen. To react when a particular screen gains or loses focus inside the app, use your navigator’s focus events instead.