react-native-appstate-hook

A small React hook around React Native's AppState API — know when your app goes to the foreground or background, and react to memory warnings and window focus changes, without wiring up AppState.addEventListener.

Installation

npm install react-native-appstate-hook
# or
yarn add react-native-appstate-hook

Usage

import React from 'react';
import { Text, View } from 'react-native';
import useAppState from 'react-native-appstate-hook';

export default function App() {
  const { appState } = useAppState({
    onChange: (newAppState) => console.log('App state changed to', newAppState),
    onForeground: () => console.log('App came to the foreground'),
    onBackground: () => console.log('App went to the background'),
    onMemoryWarning: () => console.log('App received a memory warning'),
    onFocus: () => console.log('App window gained focus (Android only)'),
    onBlur: () => console.log('App window lost focus (Android only)'),
  });

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>App state is: {appState}</Text>
    </View>
  );
}

All settings are optional — pass only the callbacks you need.

API

Settings

useAppState takes a single, optional settings object:

Key	Type	Description
onChange	(appState: AppStateStatus) => void	Called on every app state transition, with the new state.
onForeground	() => void	Called when the app transitions into the active state.
onBackground	() => void	Called when the app leaves the active state for inactive or background.
onMemoryWarning	() => void	iOS only. Called when the OS reports a low-memory warning. This is a point-in-time signal, not a state the app stays in — it can fire while the app is active or backgrounded.
onFocus	() => void	Android only. Called when the app's window gains OS input focus.
onBlur	() => void	Android only. Called when the app's window loses OS input focus — e.g. a system dialog or another app (split-screen/multi-window) is shown over it — without the app actually backgrounding.

Return value

Key	Type	Description
appState	AppStateStatus	The current app state: active, background, or inactive (iOS only).

License

MIT