AppState

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.

Kepler version 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

Basic Usage

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.

Note: If your app has more than one app component, see Basic Usage for multiple components.

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

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 (
    <View style={styles.container}>
      <Text>Current state is: {appStateVisible}</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.

Basic Usage for multiple components

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

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

const styles = StyleSheet.create({
  container: {
    flex: 1,
    flexDirection: 'column',
    justifyContent: 'center',
    alignItems: 'center'
  },
  displayText: {
    fontSize: 20,
    fontWeight: 'bold'
  },
  commentText: {
    fontSize: 16
  }
});

class App extends Component {
  state = {
    moduleStates: AppState.currentModuleStates
  };

  private appStateSubscriptions: NativeEventSubscription[];

  componentDidMount() {
    console.info('AppState demo: Adding event listeners');

    this.appStateSubscriptions = [];

    this.appStateSubscriptions.push(
      AppState.addEventListener(
        'moduleChange',
        this.handleModuleChange
      )
    );
    this.appStateSubscriptions.push(
      AppState.addEventListener(
        'memoryWarning',
        this.handleMemoryWarning
      )
    );
  }

  componentWillUnmount() {
    console.info('AppState demo: Removing event listeners');
    this.appStateSubscriptions.forEach((subscription) => {
      subscription.remove();
    });
  }

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

  handleMemoryWarning = () => {
    console.info('AppState posted memory warning');
  };

  render() {
    return (
      <View style={styles.container}>
        <Text style={styles.displayText}>Module states: </Text>
        {this.state.moduleStates &&
          this.state.moduleStates.map(
            (
              element: {
                module_name: string;
                module_state: string;
              },
              i: number
            ) => (
              <Text key={i} style={styles.commentText}>
                {`App component: ${element.module_name}, state: ${element.module_state}`}
              </Text>
            )
          )}
      </View>
    );
  }
}

export default App;
AppRegistry.registerComponent('App', () => App);

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.

When and app component changes state a 'change' event is emitted. This event does not tell you which module's state changed.

If your app has multiple app components, it should listen for moduleChange events to get the states for specific modules.

moduleChange

This event is received when the state of any app component has changed. The listener is called with an array of ModuleStateKepler 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 an Kepler app component backgrounds it's 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

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

blur

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.

removeEventListener()

removeEventListener(eventType, listener);

Deprecated This method is deprecated; use the remove() method on the EventSubscription returned by addEventListener().

Remove a handler by passing the change (or moduleChange ) event type and the handler.

Properties

currentState

static currentState: AppStateStatus;

currentModuleStates

AppState.currentModuleStates; // array of ModuleStateKepler objects

Last updated: Sep 30, 2025