Skip to main content
The AppState API tells you if the app is in the foreground or background and notifies you when the state changes. This is useful for determining whether to pause/resume activities, save data, or adjust behavior based on app visibility.

​
Import

import { AppState } from 'react-native';

​
Properties

​
currentState

Returns the current state of the application. 
const state = AppState.currentState;
Returns: AppStateStatus - One of: 'active', 'background', 'inactive', 'extension', or 'unknown'

​
isAvailable

Indicates whether the AppState API is available. 
const available = AppState.isAvailable;
Returns: boolean

​
Methods

​
addEventListener()

Add a listener to monitor app state changes. 
const subscription = AppState.addEventListener(type, handler);
​
type
string
required
The event type to listen for:
  • 'change': App state has changed (active, background, inactive)
  • 'memoryWarning': Device is running low on memory
  • 'focus': App has gained focus (Android only)
  • 'blur': App has lost focus (Android only)
​
handler
function
required
Callback function invoked when the event occurs.For 'change' events, receives the new AppStateStatus as parameter. For other events, receives no parameters.
Returns: EventSubscription - Object with a remove() method to unsubscribe.

​
App States

​
active

The app is running in the foreground and the user is actively interacting with it.

​
background

The app is running in the background. The user is either:
  • In another app
  • On the home screen
  • On another Activity (Android)

​
inactive (iOS only)

Transitional state that occurs when moving between foreground and background, or during:
  • Entering the multitasking view
  • Opening the Notification Center
  • Receiving an incoming call
  • Opening Control Center

​
extension

The app is running as an app extension (rare).

​
unknown

The app state is not yet determined.

​
Examples

​
Basic Usage

import React, { useEffect, useState } from 'react';
import { AppState, Text, View } from 'react-native';

const AppStateExample = () => {
  const [appState, setAppState] = useState(AppState.currentState);

  useEffect(() => {
    const subscription = AppState.addEventListener('change', (nextAppState) => {
      setAppState(nextAppState);
    });

    return () => {
      subscription.remove();
    };
  }, []);

  return (
    <View>
      <Text>Current App State: {appState}</Text>
    </View>
  );
};

​
Handling Active/Inactive Transitions

import React, { useEffect, useRef } from 'react';
import { AppState } from 'react-native';

const AppComponent = () => {
  const appState = useRef(AppState.currentState);

  useEffect(() => {
    const subscription = AppState.addEventListener('change', (nextAppState) => {
      if (
        appState.current.match(/inactive|background/) &&
        nextAppState === 'active'
      ) {
        console.log('App has come to the foreground!');
        // Resume activities, refresh data, etc.
      }

      if (
        appState.current === 'active' &&
        nextAppState.match(/inactive|background/)
      ) {
        console.log('App has gone to the background!');
        // Pause activities, save data, etc.
      }

      appState.current = nextAppState;
      console.log('AppState changed to:', appState.current);
    });

    return () => {
      subscription.remove();
    };
  }, []);

  return null;
};

​
Pausing/Resuming Activities

import React, { useEffect, useState } from 'react';
import { AppState } from 'react-native';

const VideoPlayer = () => {
  const [isPlaying, setIsPlaying] = useState(true);

  useEffect(() => {
    const subscription = AppState.addEventListener('change', (nextAppState) => {
      if (nextAppState === 'background' || nextAppState === 'inactive') {
        // Pause video when app goes to background
        setIsPlaying(false);
      } else if (nextAppState === 'active') {
        // Resume video when app returns to foreground
        setIsPlaying(true);
      }
    });

    return () => {
      subscription.remove();
    };
  }, []);

  return (
    // Video player component
    null
  );
};

​
Memory Warning Handler

import React, { useEffect } from 'react';
import { AppState, Alert } from 'react-native';

const MemoryMonitor = () => {
  useEffect(() => {
    const subscription = AppState.addEventListener('memoryWarning', () => {
      console.warn('Memory warning received!');
      // Clear caches, release resources, etc.
      Alert.alert(
        'Memory Warning',
        'The device is running low on memory. Some features may be limited.',
      );
    });

    return () => {
      subscription.remove();
    };
  }, []);

  return null;
};

​
Focus/Blur Events (Android)

import React, { useEffect } from 'react';
import { AppState, Platform } from 'react-native';

const FocusMonitor = () => {
  useEffect(() => {
    if (Platform.OS === 'android') {
      const focusSubscription = AppState.addEventListener('focus', () => {
        console.log('App gained focus');
      });

      const blurSubscription = AppState.addEventListener('blur', () => {
        console.log('App lost focus');
      });

      return () => {
        focusSubscription.remove();
        blurSubscription.remove();
      };
    }
  }, []);

  return null;
};

​
Tracking Time in Foreground

import React, { useEffect, useRef, useState } from 'react';
import { AppState, Text, View } from 'react-native';

const TimeTracker = () => {
  const [foregroundTime, setForegroundTime] = useState(0);
  const startTime = useRef(Date.now());

  useEffect(() => {
    const subscription = AppState.addEventListener('change', (nextAppState) => {
      if (nextAppState === 'active') {
        startTime.current = Date.now();
      } else if (nextAppState === 'background') {
        const elapsed = Date.now() - startTime.current;
        setForegroundTime((prev) => prev + elapsed);
      }
    });

    return () => {
      subscription.remove();
    };
  }, []);

  return (
    <View>
      <Text>Time in foreground: {Math.floor(foregroundTime / 1000)}s</Text>
    </View>
  );
};

​
Platform Differences

​
iOS

  • Supports 'active', 'background', and 'inactive' states
  • The 'inactive' state is used during transitions and system interactions
  • Background execution time is limited by iOS

​
Android

  • Primarily uses 'active' and 'background' states
  • The 'inactive' state is less common
  • Additional 'focus' and 'blur' events for more granular control
  • Background execution policies vary by Android version

​
Best Practices

Always clean up event listeners in the cleanup function returned by useEffect to prevent memory leaks.
Don’t rely on currentState property for critical logic. Use event listeners instead, as the state may have changed between reads.
On Android, the app may be killed when in the background. Save important data before the app goes to the background.

​
Common Use Cases

  • Auto-pause media: Pause audio/video when app goes to background
  • Save data: Persist user data before app is backgrounded
  • Refresh content: Reload data when app returns to foreground
  • Analytics: Track session duration and user engagement
  • Resource management: Release heavy resources when app is not visible
  • Real-time updates: Pause/resume subscriptions based on app state

Build docs developers (and LLMs) love

Get started for freeTalk to us