https://github.com/douglasjunior/react-native-applifecycle
⚛ Enhances the reliability of managing app lifecycles across iOS and Android platforms, ensuring consistent behavior regarding foreground and background states.
https://github.com/douglasjunior/react-native-applifecycle
android appstate ios lifecycle react-native
Last synced: about 2 months ago
JSON representation
⚛ Enhances the reliability of managing app lifecycles across iOS and Android platforms, ensuring consistent behavior regarding foreground and background states.
- Host: GitHub
- URL: https://github.com/douglasjunior/react-native-applifecycle
- Owner: douglasjunior
- License: mit
- Created: 2024-04-20T19:54:08.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-12T01:55:10.000Z (2 months ago)
- Last Synced: 2025-04-15T12:56:40.518Z (about 2 months ago)
- Topics: android, appstate, ios, lifecycle, react-native
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/react-native-applifecycle
- Size: 406 KB
- Stars: 92
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# React-Native App Lifecycle
[](https://github.com/douglasjunior/react-native-applifecycle/blob/master/LICENSE)
[](https://www.npmjs.com/package/react-native-applifecycle)
[](https://www.npmjs.com/package/react-native-applifecycle?activeTab=versions)
⚛ Enhances the reliability of managing app lifecycles across iOS and Android platforms, ensuring consistent behavior regarding `foreground` and `background` states.
It implements the [Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) for **Android** and falls back to the [AppState](https://reactnative.dev/docs/appstate) for **iOS**.
## Why Use This?
The original [AppState](https://reactnative.dev/docs/appstate) API provided by React Native behaves differently between Android and iOS, particularly regarding the `background` state:
- On iOS, the `background` state signifies that the entire app is in the background.
- On Android, the `background` state indicates that the React Native Activity is in the background, which might not necessarily mean the entire app is in the background.
By using `react-native-applifecycle`, you can handle these differences seamlessly across both platforms, ensuring that the state `background` will be dispatched only when the entire app is in background.
## Install
Install dependency package
```bash
yarn add react-native-applifecycle
```
Or
```bash
npm i -S react-native-applifecycle
```
## Usage
The App Lifecycle API is compatible with the original [AppState](https://reactnative.dev/docs/appstate).
### Subscribing to the `change` listener:
```tsx
import {AppLifecycle} from 'react-native-applifecycle';
const App = () => {
useEffect(() => {
const listener = AppLifecycle.addEventListener('change', state => {
// do something
});
return () => listener.remove();
}, []);
return ;
}
export default App;
```
### Getting the current state with `hook`:
```tsx
import {useAppLifecycle} from 'react-native-applifecycle';
const App = () => {
const currentLifecycle = useAppLifecycle();
// do something
return ;
}
export default App;
```
For more details, see the [Sample Project](https://github.com/douglasjunior/react-native-applifecycle/blob/main/Sample/App.tsx).
## Lifecycle 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
- [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 [React Native documentation](https://reactnative.dev/docs/appstate#app-states).
## Events
### `change`
This event is received when the app state has changed. The listener is called with one of the current app state values.
### `memoryWarning`, `focus`, `blur`, etc
Falls back to [AppState](https://reactnative.dev/docs/appstate#events)
## Methods
### `addEventListener()`
```ts
static addEventListener(
type: AppStateEvent,
listener: (state: AppStateStatus) => void,
): NativeEventSubscription;
```
Sets up a function that will be called whenever the specified event type on Lifecycle occurs. Valid values for `eventType` are listed above. Returns the `EventSubscription`.
## Properties
### `currentState`
```ts
static currentState: AppStateStatus;
```
## Jest mock
```js
jest.mock('react-native-applifecycle/dist/AppLifecycle', () => require('react-native-applifecycle/jest/AppLifecycleMock'));
```
## Contribute
New features, bug fixes and improvements are welcome! For questions and suggestions use the [issues](https://github.com/douglasjunior/react-native-applifecycle/issues).
[](https://paypal.me/douglasnassif)
## Star History
[](https://star-history.com/#douglasjunior/react-native-applifecycle)
## License
```
The MIT License (MIT)
Copyright (c) 2024 Douglas Nassif Roma Junior
```
See the full [license file](https://github.com/douglasjunior/react-native-applifecycle/blob/master/LICENSE).