KeplerAppState
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 Kepler, 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 Kepler 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.
useKeplerAppStateManager: () => IKeplerAppStateManager;
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.
useGetCurrentKeplerAppStateCallback = (): () => KeplerAppStateStatus
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 = (): KeplerAppStateCallback
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 = (): () => KeplerAppStateWithReplay
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 = (): () => IComponentInstance
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(): KeplerAppStateStatus
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
addAppStateListener(eventName: KeplerAppStateEvent, callback: OnEventCallback): EventSubscription
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(eventName: KeplerAppStateEvent, callback: OnEventWithReplayCallback): EventSubscription
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(): IComponentInstance
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
type KeplerAppStateStatus = 'active' | 'background' | 'inactive' | 'unknown';
- 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
type KeplerAppStateEvent = 'change' | 'memoryWarning' | 'blur' | 'focus' | 'reconfigure' | 'displayChange';
- 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
type KeplerAppReconfigureReason = 'homePressed';
KeplerReconfigureReasonData
interface KeplerReconfigureReasonData {
{
rootTag: number;
reconfigureReason: KeplerAppReconfigureReason;
}
KeplerAppStateWithReplay
interface KeplerAppStateWithReplay {
isReplayed: boolean;
appState?: KeplerAppStateChange;
}
KeplerAppDisplayStatus
type KeplerAppDisplayStatus = 'displayDisconnected' | 'displayConnected';`
KeplerAppStateChangeData
type KeplerAppStateChangeData = KeplerAppStateStatus | KeplerReconfigureReasonData | KeplerAppDisplayStatus;`
KeplerAppStateChange
type KeplerAppStateChange = KeplerAppStateChangeData;`
OnEventCallback
type OnEventCallback = (event: KeplerAppStateChangeData) => void;`
OnEventWithReplayCallback
type OnEventWithReplayCallback = (event: KeplerAppStateWithReplay) => void;`
OnAppStateEventCallback
type OnAppStateEventCallback = (event: KeplerAppStateChange) => void;`
Discontinued. Use OnEventCallback instead.
OnAppStateEventWithReplayCallback
type OnAppStateEventWithReplayCallback = (event: KeplerAppStateWithReplay) => void;`
Discontinued. Use OnEventWithReplayCallback instead.
Examples
Comprehensive example app
This example demonstrates a complete implementation of KeplerAppState functionality in a React Native Kepler 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.
import {
IKeplerAppStateManager,
KeplerAppDisplayStatus,
KeplerAppStateChangeData,
KeplerAppStateStatus,
KeplerAppStateWithReplay,
KeplerReconfigureReasonData,
useKeplerAppStateManager,
} from '@amzn/react-native-kepler';
import React, { useEffect, useState } from 'react';
import { AppRegistry, StyleSheet, Text, View } from 'react-native';
const styles = StyleSheet.create({
container: {
flex: 1,
flexDirection: 'column',
justifyContent: 'center',
alignItems: 'center',
},
displayText: {
fontSize: 20,
fontWeight: 'bold',
color: 'white',
},
commentText: {
fontSize: 16,
color: 'white',
},
});
const KeplerAppStateApp = () => {
const keplerAppStateManager: IKeplerAppStateManager =
useKeplerAppStateManager();
const [appStateData, setAppState] = useState<KeplerAppStateStatus>(
keplerAppStateManager.getCurrentState,
);
const [homePressedCounter, setHomePressedCounter] = useState(0);
const [displayDisconnectCounter, setDisplayDisconnectCounter] = useState(0);
const [displayConnectCounter, setDisplayConnectCounter] = useState(0);
const [appFocusState, setAppFocusState] = useState('FOCUSED');
useEffect(() => {
console.log('KeplerAppState demo: Adding event listeners');
// Keeping the event handler as part of useEffect to avoid re-render when this event is fired
const handleAppStateChange = (nextAppState: KeplerAppStateChangeData) => {
if (
appStateData.match(/inactive|background/) &&
nextAppState === 'active'
) {
console.log('KeplerAppState demo has come to the foreground');
}
setAppState(nextAppState as KeplerAppStateStatus);
console.log(`KeplerAppState change: ${nextAppState}`);
};
const handleAppStateChangeWithReplayedEvents = (
keplerAppStateData: KeplerAppStateWithReplay,
) => {
if (keplerAppStateData.isReplayed) {
console.log(
`KeplerAppState demo has received replayed change event : ${JSON.stringify(
keplerAppStateData,
)}`,
);
} else {
console.log(
`KeplerAppState demo has received change event: ${JSON.stringify(
keplerAppStateData,
)}`,
);
}
if (
appStateData.match(/inactive|background/) &&
keplerAppStateData.appState === 'active'
) {
console.log('KeplerAppState demo has come to the foreground');
}
setAppState(keplerAppStateData.appState as KeplerAppStateStatus);
};
const changeSubscription = keplerAppStateManager.addAppStateListener(
'change',
handleAppStateChange,
);
const memoryWarningSubscription = keplerAppStateManager.addAppStateListener(
'memoryWarning',
handleMemoryWarning,
);
const reconfigureSubscription = keplerAppStateManager.addAppStateListener(
'reconfigure',
handleReconfigure,
);
const focusSubscription = keplerAppStateManager.addAppStateListener(
'focus',
handleFocus,
);
const blurSubscription = keplerAppStateManager.addAppStateListener(
'blur',
handleBlur,
);
const displayChangeSubscription = keplerAppStateManager.addAppStateListener(
'displayChange',
handleDisplayChange,
);
// Handle replayed events with addEventListenerWithReplay method from useKeplerAppStateManager hook
const changeWithReplaySubscription =
keplerAppStateManager.addEventListenerWithReplay(
'change',
handleAppStateChangeWithReplayedEvents,
);
const reconfigureWithReplaySubscription =
keplerAppStateManager.addEventListenerWithReplay(
'reconfigure',
handleReconfigureWithReplayedEvents,
);
const memoryWarningWithReplaySubscription =
keplerAppStateManager.addEventListenerWithReplay(
'memoryWarning',
handleMemoryWarningWithReplayedEvents,
);
const focusWithReplaySubscription =
keplerAppStateManager.addEventListenerWithReplay(
'focus',
handleFocusWithReplayedEvents,
);
const blurWithReplaySubscription =
keplerAppStateManager.addEventListenerWithReplay(
'blur',
handleBlurWithReplayedEvents,
);
const displayChangeWithReplaySubscription =
keplerAppStateManager.addEventListenerWithReplay(
'displayChange',
handleDisplayChangeWithReplayedEvents,
);
// Cleanup subscriptions on unmount
return () => {
console.log('KeplerAppState demo: Removing event listeners');
// Individually remove each listener
changeSubscription.remove();
memoryWarningSubscription.remove();
reconfigureSubscription.remove();
focusSubscription.remove();
blurSubscription.remove();
displayChangeSubscription.remove();
changeWithReplaySubscription.remove();
reconfigureWithReplaySubscription.remove();
memoryWarningWithReplaySubscription.remove();
focusWithReplaySubscription.remove();
blurWithReplaySubscription.remove();
displayChangeWithReplaySubscription.remove();
};
}, [keplerAppStateManager, appStateData]);
// The empty dependency array means this effect runs once when the component mounts and
// cleans up when it unmounts
const handleMemoryWarning = () => {
console.log('KeplerAppState demo has received memory warning');
};
const handleReconfigure = (reason: KeplerAppStateChangeData) => {
const reconfigureReasonData = reason as KeplerReconfigureReasonData;
console.log(
`KeplerAppState demo has received reconfigure : ${JSON.stringify(
reconfigureReasonData,
)}`,
);
if (reconfigureReasonData.reconfigureReason === 'homePressed') {
setHomePressedCounter(prevCounter => prevCounter + 1);
}
};
const handleFocus = () => {
setAppFocusState('FOCUSED');
console.log('KeplerAppState demo has received Focus Event');
};
const handleBlur = () => {
setAppFocusState('BLURRED');
console.log('KeplerAppState demo has received Blur Event');
};
const handleDisplayChange = (reason: KeplerAppStateChangeData) => {
const displayChangeData = reason as KeplerAppDisplayStatus;
console.log(
`KeplerAppState demo has received display event : ${JSON.stringify(
displayChangeData,
)}`,
);
if (displayChangeData === 'displayConnected') {
setDisplayConnectCounter(prevCounter => prevCounter + 1);
}
if (displayChangeData === 'displayDisconnected') {
setDisplayDisconnectCounter(prevCounter => prevCounter + 1);
}
};
const handleReconfigureWithReplayedEvents = (
keplerAppStateData: KeplerAppStateWithReplay,
) => {
if (keplerAppStateData.isReplayed) {
console.log(
`KeplerAppState demo has received replayed reconfigure event : ${JSON.stringify(
keplerAppStateData,
)}`,
);
} else {
console.log(
`KeplerAppState demo has received reconfigure event: ${JSON.stringify(
keplerAppStateData,
)}`,
);
}
const reconfigureReasonData =
keplerAppStateData.appState as KeplerReconfigureReasonData;
if (reconfigureReasonData.reconfigureReason === 'homePressed') {
setHomePressedCounter(prevCounter => prevCounter + 1);
}
};
const handleMemoryWarningWithReplayedEvents = (
keplerAppStateData: KeplerAppStateWithReplay,
) => {
if (keplerAppStateData.isReplayed) {
console.log(
`KeplerAppState demo has received replayed memory warning event : ${JSON.stringify(
keplerAppStateData,
)}`,
);
} else {
console.log(
`KeplerAppState demo has received memory warning event: ${JSON.stringify(
keplerAppStateData,
)}`,
);
}
};
const handleFocusWithReplayedEvents = (
keplerAppStateData: KeplerAppStateWithReplay,
) => {
if (keplerAppStateData.isReplayed) {
console.log(
`KeplerAppState demo has received replayed Focus event : ${JSON.stringify(
keplerAppStateData,
)}`,
);
} else {
console.log(
`KeplerAppState demo has received Focus event: ${JSON.stringify(
keplerAppStateData,
)}`,
);
}
setAppFocusState('FOCUSED');
};
const handleBlurWithReplayedEvents = (
keplerAppStateData: KeplerAppStateWithReplay,
) => {
if (keplerAppStateData.isReplayed) {
console.log(
`KeplerAppState demo has received replayed Blur event : ${JSON.stringify(
keplerAppStateData,
)}`,
);
} else {
console.log(
`KeplerAppState demo has received Blur event: ${JSON.stringify(
keplerAppStateData,
)}`,
);
}
setAppFocusState('BLURRED');
};
const handleDisplayChangeWithReplayedEvents = (
keplerAppStateData: KeplerAppStateWithReplay,
) => {
if (keplerAppStateData.isReplayed) {
console.log(
`KeplerAppState demo has received replayed display event : ${JSON.stringify(
keplerAppStateData,
)}`,
);
} else {
console.log(
`KeplerAppState demo has received display event: ${JSON.stringify(
keplerAppStateData,
)}`,
);
}
if (keplerAppStateData.appState === 'displayConnected') {
console.log('KeplerAppState demo has received displayConnected event');
} else if (keplerAppStateData.appState === 'displayDisconnected') {
console.log('KeplerAppState demo has received displayDisconnected event');
}
setAppState(keplerAppStateData.appState as KeplerAppStateStatus);
};
return (
<View style={styles.container}>
<Text style={styles.displayText}>Current state is: {appStateData}</Text>
<Text style={styles.commentText}>
(When UI is displaying, the state will always be active
</Text>
<Text style={styles.commentText}>in KeplerScript applications)</Text>
<Text style={styles.displayText}>
HomeButton Counter: {homePressedCounter}
</Text>
<Text style={styles.displayText}>
Display Connection Counter: {displayConnectCounter}
</Text>
<Text style={styles.displayText}>
Display Disconnection Counter: {displayDisconnectCounter}
</Text>
<Text style={styles.displayText}>
Current Focus state is: {appFocusState}
</Text>
</View>
);
};
export default KeplerAppStateApp;
AppRegistry.registerComponent('KeplerAppStateApp', () => KeplerAppStateApp);
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.
import {
IKeplerAppStateManager,
KeplerAppStateEvent,
KeplerAppStateStatus,
KeplerAppStateWithReplay,
useKeplerAppStateManager,
} from '@amzn/react-native-kepler';
import React, { useEffect, useState } from 'react';
import { StyleSheet, Text, View } from 'react-native';
const styles = StyleSheet.create({
container: {
flex: 1,
flexDirection: 'column',
justifyContent: 'center',
alignItems: 'center',
padding: 20,
},
stateText: {
fontSize: 20,
fontWeight: 'bold',
marginBottom: 10,
},
eventText: {
fontSize: 16,
marginBottom: 5,
},
});
const AppStateMonitor = () => {
const keplerAppStateManager: IKeplerAppStateManager =
useKeplerAppStateManager();
const [currentState, setCurrentState] = useState<KeplerAppStateStatus>(
keplerAppStateManager.getCurrentState,
);
const [lastEvent, setLastEvent] = useState<string>('');
useEffect(() => {
// Monitor app state changes
const subscriptions = [
keplerAppStateManager.addEventListenerWithReplay(
'change' as KeplerAppStateEvent,
(event: KeplerAppStateWithReplay) => {
const state = event.appState as KeplerAppStateStatus;
setCurrentState(state);
setLastEvent(
`State change: ${state} (${event.isReplayed ? 'Replayed' : 'New'})`,
);
},
),
// Monitor focus events
keplerAppStateManager.addEventListenerWithReplay(
'focus' as KeplerAppStateEvent,
(event: KeplerAppStateWithReplay) => {
setLastEvent(
`Focus event (${event.isReplayed ? 'Replayed' : 'New'})`,
);
},
),
// Monitor display changes
keplerAppStateManager.addEventListenerWithReplay(
'displayChange' as KeplerAppStateEvent,
(event: KeplerAppStateWithReplay) => {
setLastEvent(
`Display change: ${event.appState} (${
event.isReplayed ? 'Replayed' : 'New'
})`,
);
},
),
];
// Cleanup function
return () => {
subscriptions.forEach(subscription => subscription.remove());
};
}, [keplerAppStateManager]);
return (
<View style={styles.container}>
<Text style={styles.stateText}>Current App State: {currentState}</Text>
<Text style={styles.eventText}>Last Event: {lastEvent}</Text>
</View>
);
};
export default AppStateMonitor;
Last updated: Sep 30, 2025
