expo-lock-state

Device lock / unlock (screen on/off) events for React Native + Expo, built on the Expo Modules API.

Use it to react to the device locking even while your app is backgrounded — for example, to dismiss Picture-in-Picture or pause media when the screen locks (a case AppState can't detect once the app is already in the background).

Platform signals

| Platform | onLock | onUnlock | Notes | |---|---|---|---| | iOS | protectedDataWillBecomeUnavailable | protectedDataDidBecomeAvailable | Requires a device passcode. Fires a few seconds after lock (iOS data-protection grace period). App-Store-safe (no private APIs). | | Android | ACTION_SCREEN_OFF | ACTION_USER_PRESENT | Fires immediately on screen off. No permissions needed. |

Requirements

• A custom dev build / prebuilt app (this is a native module — it does not work in Expo Go).
• Expo SDK 50+ (Expo Modules API).

Install

npm install expo-lock-state
# then rebuild the native app:
npx expo prebuild
npx expo run:ios     # or: npx expo run:android

Usage

import { LockState } from "expo-lock-state"

// `LockState` is null if the native module isn't in the running binary
// (e.g. an old dev build), so always null-check.
const sub = LockState?.addListener("onLock", () => {
  // device locked — e.g. dismiss PiP + pause playback
})

// later
sub?.remove()

Events

• onLock — device locked / screen off.
• onUnlock — device unlocked.

License

MIT