@galvo/immersive-mode

True full-screen immersive mode for React Native games on Android — and the part everyone else leaves out: it excludes the full-height left and right edges from the system back gesture, so a whole-screen-swipe game stops navigating backwards mid-play.

No-op on iOS and web, by design. Drop it in unconditionally.

npx expo install @galvo/immersive-mode

Requires a development build (it ships native code, so it does not run in Expo Go).

Use

import { useImmersiveGameMode } from '@galvo/immersive-mode';

export function GameScreen() {
  const [paused, setPaused] = useState(false);
  const [dead, setDead] = useState<number | null>(null);

  // Immersive while actually playing; bars come back on pause/death automatically.
  useImmersiveGameMode(!paused && dead === null);

  return <YourGame />;
}

That is the whole API surface most apps need. The hook restores the system bars whenever active flips false, when the app is backgrounded, and on unmount — so the task switcher is always reachable and you cannot strand a user in a chrome-less screen.

Imperative access is available if you are driving it from outside React:

import { ImmersiveMode } from '@galvo/immersive-mode';

ImmersiveMode.enter(48); // edge band in dp, default 48
ImmersiveMode.exit();

Why this exists

Android's setSystemGestureExclusionRects caps you at 200dp per edge. For a game where the player swipes anywhere on the screen, that is not enough — a swipe starting below the excluded band is captured by the system back gesture and the player gets thrown out of the level.

Entering sticky immersive (BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE) lifts that cap, which lets this module claim genuinely full-height left/right bands. The bottom home gesture stays mandatory — that one is not negotiable on Android, and should not be.

The result: swipes belong to your game, the system stays escapable, and nothing changes on the platforms where none of this applies.

API

Export	Signature	Notes
useImmersiveGameMode	(active: boolean, edgeBandDp?: number) => void	The recommended surface. Handles AppState and unmount.
ImmersiveMode.enter	(edgeBandDp?: number) => void	Imperative. Default 48.
ImmersiveMode.exit	() => void	Restores bars and clears exclusion rects.

The native module is loaded with requireOptionalNativeModule, so on web or in a JS-only context before a dev build the calls are hard no-ops rather than throwing.

Platform behaviour

Platform	Behaviour
Android	Sticky immersive + full-height L/R gesture exclusion
iOS	No-op (native stub resolves, calls do nothing)
Web	No-op (native module absent)

License

MIT — see LICENSE.

Built for Galvo, a catalog of GPU effects and games for React Native.