Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Get Started
Design and Develop
Publish
Reference
Support
Skip to main content
App state in the normal React Native context applies to the app process. An app as a whole is in the foreground or the backgrounded. The AppState module provided through ‘react-native’ does not support fetching and listening for app state changes for multiple interactive components that are part of the same application process. On Vega, an app process can have separate interactive components that may be backgrounded or foregrounded. Foregrounded (or active) means that an interactive component can have visible UI. Backgrounded means that all UI for that component is not visible. The app process itself is neither backgrounded or foregrounded. Interactive components may have one or more windows. Whether or not a specified window is an active responder to handle input events, such as text input or clicks, is a separate matter. App state does not refer to the responder state of a particular window owned by a interactive component. It refers to the state of the component itself and in turn all of the UI elements it displays. React Native for Vega provides new custom hooks and the KeplerAppStateManager for interactive components to listen to app state changes.

Methods

useKeplerAppStateManager

useKeplerAppStateManager() is a custom hook that returns a KeplerAppStateManager instance that can be used to query and listen to app state changes. Please follow the React’s Rules of Hooks when calling this hook.

useGetCurrentKeplerAppStateCallback

Discontinued. Use getCurrentState instead. useGetCurrentKeplerAppStateCallback is a custom hook that returns a callback that returns the current app state of your interactive component. Please follow the React’s Rules of Hooks when calling this hook. The returned callback function takes no parameters and returns KeplerAppStateStatus, which is described below in the types section.
Note: Calling the hook does not return the app state. You have to invoke the callback function returned by the hook to get your interactive component’s app state.

useAddKeplerAppStateListenerCallback

Discontinued. Use addAppStateListener instead.
useAddKeplerAppStateListenerCallback is a custom hook that returns a callback that adds a listener for the specified event. Please follow the React’s Rules of Hooks when calling this hook. The returned callback function, typed as KeplerAppStateCallback, takes two parameters, the event name (KeplerAppStateEvent) to subscribe to and the callback function (OnEventCallback) to invoke when the event occurs. The callback function returns a handle to the subscription. Call remove() to remove the subscription. Note: Calling the hook does not register an app state listener. You have to invoke the callback function returned by the hook to register an app state listener.
You can also call the method with a OnAppStateEventCallback callback (instead of OnEventCallback), but this variant is discontinued.

useAddKeplerAppStateListenerWithReplayCallback

Discontinued. Use addEventListenerWithReplay instead.
useAddKeplerAppStateListenerWithReplayCallback is a custom hook that returns a callback that adds a listener for the specified event. The callback is immediately invoked if any past events have occurred before the app subscribed to the listeners (events will be replayed). Otherwise it behaves like useAddKeplerAppStateListenerCallback(). Please follow the React’s Rules of Hooks when calling this hook. The returned callback function takes no parameters and returns KeplerAppStateWithReplay, which is described below in the types section. Note: Replayed events will be sent in the order in which their respective listeners are added.
Note: Only the first listener of a particular event will receive the replayed event.
Calling the hook does not register an app state listener. You have to invoke the callback function returned by the hook to register an app state listener.

useComponentInstance

Discontinued. Use getComponentInstance instead.
useComponentInstance is a custom hook that provides an interface, IComponentInstance, which represents an application component. This interface includes properties such as the component’s name and type.

Classes

KeplerAppStateManager

getCurrentState

getCurrentState returns the current app state of your interactive component. It takes no parameters and returns KeplerAppStateStatus, which is described below in the types section.

addAppStateListener

Adds a listener for the specified event. addAppStateListener adds a listener for the specified event. It takes two parameters, the event name (KeplerAppStateEvent) to subscribe to and the callback function (OnEventCallback) to invoke when the event occurs. Returns a handle to the subscription. Call remove() to remove the subscription.

addEventListenerWithReplay

addEventListenerWithReplay adds a listener for the specified event and this will capture and replay the events that came before it was attached. Note: Replayed events will be sent in the order in which their respective listeners are added.
Only the first listener of a particular event will receive the replayed event.

getComponentInstance

getComponentInstance returns an interface of type IComponentInstance, which represents an application component. This interface includes properties such as the component’s name and type.

Types

KeplerAppStateStatus

  • active: The app is running in the foreground.
  • background: The app is running in the background. The user is either in another app or on the home screen.
  • inactive: This is a transition state that currently never happens for typical React Native apps.
  • unknown : Initial value until the current app state is determined.

KeplerAppStateEvent

  • change: This even is received when the app state has changed.
  • memoryWarning: Received when the app receives a memory warning.
  • 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.
  • reconfigure: Received when an application reconfiguration event occurs.
  • displayChange - Received when a display is connected or disconnected.

KeplerAppReconfigureReason

KeplerReconfigureReasonData

KeplerAppStateWithReplay

KeplerAppDisplayStatus

KeplerAppStateChangeData

KeplerAppStateChange

OnEventCallback

OnEventWithReplayCallback

OnAppStateEventCallback

Discontinued. Use OnEventCallback instead.

OnAppStateEventWithReplayCallback

Discontinued. Use OnEventWithReplayCallback instead.

Examples

Comprehensive example app

This example demonstrates a complete implementation of KeplerAppState functionality in a React Native Vega application. The component manages multiple aspects of application state, including foreground/background transitions, memory warnings, home button interactions, and display connection status. It showcases both standard event handling and event replay capabilities, making it particularly useful for applications that need comprehensive state management. The following example includes counters for various events and displays the current application state, providing visual feedback for state changes. Note how it handles both immediate events and replayed events separately.

Use addEventListenerWithReplay from KeplerAppStateManager

The following example shows a focused implementation of event replay functionality. Unlike the comprehensive example above, this component specifically demonstrates how to capture and handle events that might occur before component mounting. It’s particularly useful in scenarios where missing initial state changes could impact application behavior. This streamlined monitor displays both the current state and the most recent event, clearly distinguishing between new and replayed events.
Last modified on December 10, 2025