AppState

@deprecated. For App State support for React Native for Vega Interactive Applications, see VegaAppState. Do not use the AppState module provided through 'react-native'.

AppState can tell you if the app is in the foreground or background, and notify you when the state changes.

AppState is frequently used to determine the intent and proper behavior when handling push notifications.

Vega version 2 (v2) applications can get the state for individual app components within the application process.

App States

• active - The app is running in the foreground
• background - The app is running in the background. The user is either:
  • in another app
  • on the home screen
  • [Android] on another Activity (even if it was launched by your app)
• [iOS] inactive - This is a state that occurs when transitioning between foreground & background, and during periods of inactivity such as entering the multitasking view, opening the Notification Center or in the event of an incoming call.

For more information, see Apple's documentation

Basic Usage (other than Vega v2)

Vega v2 applications with more than one app component should skip down to the Vega v2 Basic Usage section below.

To see the current state, you can check AppState.currentState, which will be kept up-to-date. However, currentState will be null at launch while AppState retrieves it over the bridge.

import React, {useRef, useState, useEffect} from 'react';
import {AppState, StyleSheet, Text} from 'react-native';
import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context';

const AppStateExample = () => {
  const appState = useRef(AppState.currentState);
  const [appStateVisible, setAppStateVisible] = useState(appState.current);

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

      appState.current = nextAppState;
      setAppStateVisible(appState.current);
      console.log('AppState', appState.current);
    });

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

  return (
    <SafeAreaProvider>
      <SafeAreaView style={styles.container}>
        <Text>Current state is: {appStateVisible}</Text>
      </SafeAreaView>
    </SafeAreaProvider>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});

export default AppStateExample;

Basic Usage Vega v2

To see the current state of app components, you can check AppState.currentModuleStates, which will be kept up-to-date. However, currentModuleStates will be null at launch while AppState retrieves it over the bridge.

import React, { Component } from 'react';
import {
  AppState,
  StyleSheet,
  Text,
  View,
  ModuleStateKepler,
} from 'react-native';

class AppStateExample extends Component {
  state = {
    appState: AppState.currentState,
    moduleStates: AppState.currentModuleStates,
  };

  componentDidMount() {
    this.appStateSubscription = AppState.addEventListener(
      'change',
      this._handleAppStateChange,
    );
    this.moduleChangeSubscription = AppState.addEventListener(
      'moduleChange',
      this.handleModuleChange,
    );
  }

  componentWillUnmount() {
    if (this.appStateSubscription) {
      this.appStateSubscription.remove();
    }
    if (this.moduleChangeSubscription) {
      this.moduleChangeSubscription.remove();
    }
  }

  _handleAppStateChange = (nextAppState) => {
    if (
      this.state.appState.match(/inactive|background/) &&
      nextAppState === 'active'
    ) {
      console.log('App has come to the foreground!');
    }
    this.setState({ appState: nextAppState });
  };

  handleModuleChange = (
    nextModuleStates?: ModuleStateKepler[]
  ) => {
    this.setState({ moduleStates: nextModuleStates });
    console.info(
      'Module states change: {}',
      JSON.stringify(this.state.moduleStates)
    );
  };

  render() {
    return (
      <View style={styles.container}>
        <Text>Current state is: {this.state.appState}</Text>
        <Text>
          Module states: {JSON.stringify(this.state.moduleStates)}
        </Text>
      </View>
    );
  }
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});

export default AppStateExample;

This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the active state, and the null state will happen only momentarily. If you want to experiment with the code we recommend to use your own device instead of embedded preview.

Reference

Events

change

This event is received when the app state has changed. The listener is called with one of the current app state values.

Known issue: Vega v1 app JavaScript listeners do not receive the background event due to a design limitation. This is resolved in Vega v2.

In Vega v2 if any app component changes state a 'change' event is emitted. This event does not tell you which module's state changed. Vega v2 apps should listen for 'moduleChange' events to get the states for specific modules if your application has multiple app components.

moduleChange Vega v2

This event is received when the state of any app component has changed. The listener is called with an array of ModuleStateVega objects, one for each instantiated app component.

export interface ModuleStateKepler {
  module_name: string;
  module_state: string;
}

module_name is the name used to register the main React app component in the React Native AppRegistry for the surface (window/screen).

module_state is active or background.

When a Vega app component backgrounds its surface will be destroyed. It is not recreated by default when the component re-foregrounds. Components listening for the background change will be destroyed immediately after receiving this event if their surface is destroyed. Any asynchronous work you start in response might not complete.

App components can be backgrounded and foregrounded without terminating the app process, but a background event should occur for each foregrounded app component when an application process normally terminates.

memoryWarning

This event is used in the need of throwing memory warning or releasing it.

focus AndroidVega v2

Received when the app gains focus (the user is interacting with the app).

blur AndroidVega v2

Received when the user is not actively interacting with the app. Useful in situations when the user pulls down the notification drawer. AppState won't change but the blur event will get fired.

Methods

addEventListener()

static addEventListener(
  type: AppStateEvent,
  listener: (state: AppStateStatus) => void,
): NativeEventSubscription;

Sets up a function that will be called whenever the specified event type on AppState occurs. Valid values for eventType are listed above. Returns the EventSubscription.

Properties

currentState

static currentState: AppStateStatus;

currentModuleStates Vega v2

AppState.currentModuleStates; // array of ModuleStateVega objects

Last updated: May 13, 2026