AppState

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);

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)

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

Core APIs

Hooks

Interaction

Accessibility & Internationalization

Developer Tools

Networking

Storage

Android APIs

iOS APIs

Import

Properties

currentState

isAvailable

Methods

addEventListener()

App States

active

background

inactive (iOS only)

extension

unknown

Examples

Basic Usage

Handling Active/Inactive Transitions

Pausing/Resuming Activities

Memory Warning Handler

Focus/Blur Events (Android)

Tracking Time in Foreground

Platform Differences

iOS

Android

Best Practices

Common Use Cases

​Import

​Properties

​currentState

​isAvailable

​Methods

​addEventListener()

​App States

​active

​background

​inactive (iOS only)

​extension

​unknown

​Examples

​Basic Usage

​Handling Active/Inactive Transitions

​Pausing/Resuming Activities

​Memory Warning Handler

​Focus/Blur Events (Android)

​Tracking Time in Foreground

​Platform Differences

​iOS

​Android

​Best Practices

​Common Use Cases

Import

Properties

currentState

isAvailable

Methods

addEventListener()

App States

active

background

inactive (iOS only)

extension

unknown

Examples

Basic Usage

Handling Active/Inactive Transitions

Pausing/Resuming Activities

Memory Warning Handler

Focus/Blur Events (Android)

Tracking Time in Foreground

Platform Differences

iOS

Android

Best Practices

Common Use Cases