react-native-android-overlay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mario D.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# react-native-android-overlay
+
+A lightweight and performant React Native library for Android that allows you to render registered React Native
+components inside a floating system overlay window on top of other applications.
+
+---
+
+## Features
+
+- Render React Native components as floating overlays above other apps
+- Built on top of the new React Native architecture
+- Automatically tracks the application activity lifecycle
+- Keeps the JavaScript runtime active when the app is minimized, allowing animations, timers and JS logic to continue
+  running
+- Supports drag and move gestures with touch interception
+- Fully configurable Android foreground service notification:
+  - Title
+  - Description
+  - Icon
+  - Notification channel
+
+---
+
+## Requirements
+
+- React Native >= 0.76
+- Android >= 8.0 (API 26)
+- New Architecture enabled
+
+---
+
+## Installation
+
+```bash
+npm install react-native-android-overlay
+```
+
+or:
+
+```bash
+yarn add react-native-android-overlay
+```
+
+or:
+
+```bash
+pnpm add react-native-android-overlay
+```
+
+---
+
+## Android information
+
+The library automatically merges the required permissions into your Android manifest:
+
+```xml
+
+<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE"/>
+```
+
+### Permissions
+
+- `SYSTEM_ALERT_WINDOW`
+  - Allows displaying overlays above other applications
+
+- `FOREGROUND_SERVICE`
+  - Required to keep the overlay service alive in background
+
+- `FOREGROUND_SERVICE_SPECIAL_USE`
+  - Required on Android 14+
+
+---
+
+## Foreground service
+
+This library uses an Android foreground service to keep the React Native runtime alive while your application is
+minimized.
+
+When `foreground: true`:
+
+- Android displays a persistent foreground service notification
+- JavaScript logic continues running
+
+> NOTE: Android requires a foreground service notification to keep the service alive.
+> On Android 13+, the notification visibility depends on the user's notification permission settings.
+> By default,
+> the notification may not be visible unless the app has requested and been granted notification permission.
+
+When `foreground: false`:
+
+- Android may stop the process at any time depending on system policies
+
+---
+
+# Usage
+
+## 1. Register your overlay component
+
+In your root entry file (`index.js` / `index.ts`):
+
+```javascript
+import { AppRegistry } from 'react-native';
+import App from './App';
+import MyOverlayComponent from './MyOverlayComponent';
+
+AppRegistry.registerComponent(
+  'MainApp',
+  () => App
+);
+
+// Register component used by the overlay
+AppRegistry.registerComponent(
+  'OverlayView',
+  () => MyOverlayComponent
+);
+```
+
+---
+
+## 2. Start the overlay
+
+```typescript
+import { OverlayManager } from 'react-native-android-overlay';
+
+const startOverlay = async () => {
+  const hasPermission = await OverlayManager.hasPermission();
+
+  if (!hasPermission) {
+    OverlayManager.requestPermission();
+    return;
+  }
+
+  OverlayManager.startOverlay('OverlayView', {
+    width: 300,
+    height: 150,
+
+    x: 0,
+    y: 150,
+
+    gravity: 'bottom',
+
+    draggable: true,
+    touchable: true,
+    focusable: false,
+
+    foreground: true,
+
+    notificationTitle: 'Overlay Active',
+    notificationText: 'Overlay is running in background',
+    notificationIcon: 'ic_launcher',
+
+    channelId: 'overlay_channel',
+    channelName: 'Overlay Service'
+  });
+};
+```
+
+---
+
+## 3. Stop the overlay
+
+```typescript
+const stopOverlay = () => {
+  OverlayManager.stopOverlay('OverlayView');
+};
+```
+
+---
+
+## Example overlay component
+
+```tsx
+import { View, Text } from 'react-native';
+
+export default function MyOverlayComponent() {
+  return (
+    <View>
+      <Text>
+        Hello from overlay
+      </Text>
+    </View>
+  );
+}
+```
+
+---
+
+## Overlay resizing
+
+Resize the overlay container at runtime:
+
+```typescript
+OverlayManager.resizeOverlay(
+  320,
+  200,
+  'OverlayView'
+);
+```
+
+---
+
+## Overlay movement
+
+Move the overlay window manually from JavaScript:
+
+```typescript
+OverlayManager.startMove('OverlayView');
+
+OverlayManager.moveOverlay(
+  dx,
+  dy,
+  'OverlayView'
+);
+
+OverlayManager.commitMove('OverlayView');
+```
+
+---
+
+# API reference
+
+## OverlayManager
+
+| Method                | Arguments                                               | Returns            | Description                                 |
+|-----------------------|---------------------------------------------------------|--------------------|---------------------------------------------|
+| `hasPermission()`     | None                                                    | `Promise<boolean>` | Checks if overlay permission is granted     |
+| `requestPermission()` | None                                                    | `void`             | Opens Android overlay permission settings   |
+| `startOverlay()`      | `componentName: string, options?: OverlayOptions`       | `void`             | Starts the overlay service                  |
+| `stopOverlay()`       | `componentName?: string`                                | `void`             | Removes overlay and stops service if unused |
+| `resizeOverlay()`     | `width: number, height: number, componentName?: string` | `void`             | Changes overlay window size                 |
+| `startMove()`         | `componentName?: string`                                | `void`             | Prepares overlay movement                   |
+| `moveOverlay()`       | `dx: number, dy: number, componentName?: string`        | `void`             | Moves overlay by offset                     |
+| `commitMove()`        | `componentName?: string`                                | `void`             | Saves final overlay position                |
+
+---
+
+## OverlayOptions
+
+```typescript
+interface OverlayOptions {
+  width?: number;              // Width of the overlay window in DP
+  height?: number;             // Height of the overlay window in DP
+
+  x?: number;                  // Horizontal coordinates offset in DP. Defaults to 0
+  y?: number;                  // Vertical coordinates offset in DP. Defaults to 150dp
+
+  gravity?:
+    'top' |
+    'bottom' |
+    'center';                  // Gravity anchor for overlay positioning. Defaults to 'bottom'
+
+  draggable?: boolean;         // Enable/disable dragging gestures to move overlay (defaults to true)
+  touchable?: boolean;         // If false, touch events pass through to windows beneath (defaults to true)
+  focusable?: boolean;         // If true, overlay can receive keyboard/input focus (defaults to false)
+
+  foreground?: boolean;        // Runs overlay inside a persistent foreground service (defaults to true) so that JS logic continues running when app is minimized
+
+  notificationTitle?: string;  // Custom title for foreground service notification
+  notificationText?: string;   // Custom message text for foreground service notification
+  notificationIcon?: string;   // Resdrawable name of the notification icon (e.g. "ic_launcher")
+
+  channelId?: string;          // Notification channel ID (defaults to "OverlayServiceChannel")
+  channelName?: string;        // Notification channel name (defaults to "Overlay Service")
+}
+```

package/android/build.gradle

@@ -0,0 +1,54 @@
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.10.0'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+def isNewArchitectureEnabled() {
+    return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+if (isNewArchitectureEnabled()) {
+    apply plugin: "com.facebook.react"
+}
+
+
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+    namespace "tech.zmario.androidoverlay"
+    compileSdk safeExtGet('compileSdkVersion', 36)
+
+    defaultConfig {
+        minSdk safeExtGet('minSdkVersion', 24)
+        targetSdk safeExtGet('targetSdkVersion', 36)
+        buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+    maven {
+        url "$rootDir/../node_modules/react-native/android"
+    }
+}
+
+dependencies {
+    implementation("com.facebook.react:react-android")
+    implementation("androidx.core:core:1.12.0")
+}

package/android/settings.gradle

@@ -0,0 +1,9 @@
+pluginManagement {
+    includeBuild("../node_modules/@react-native/gradle-plugin")
+}
+
+plugins {
+    id("com.facebook.react.settings")
+}
+
+rootProject.name = "react-native-android-overlay"

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,19 @@
+<manifest xmlns:tools="http://schemas.android.com/tools"
+  xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"
+      tools:ignore="ForegroundServicesPolicy" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <application>
+        <service
+            android:name="tech.zmario.androidoverlay.service.OverlayService"
+            android:foregroundServiceType="specialUse"
+            android:enabled="true"
+            android:exported="false">
+            <property android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
+                      android:value="Overlay service to display floating view over other applications."/>
+        </service>
+    </application>
+</manifest>

package/android/src/main/java/tech/zmario/androidoverlay/OverlayPackage.java

@@ -0,0 +1,52 @@
+package tech.zmario.androidoverlay;
+
+import androidx.annotation.NonNull;
+import com.facebook.react.BaseReactPackage;
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.module.model.ReactModuleInfo;
+import com.facebook.react.module.model.ReactModuleInfoProvider;
+import com.facebook.react.uimanager.ViewManager;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import tech.zmario.androidoverlay.module.OverlayModule;
+
+public class OverlayPackage extends BaseReactPackage {
+
+  @Override
+  public NativeModule getModule(String name, @NonNull ReactApplicationContext reactContext) {
+    if (name.equals(NativeAndroidOverlaySpec.NAME)) {
+      return new OverlayModule(reactContext);
+    }
+
+    return null;
+  }
+
+  @NonNull
+  @Override
+  public ReactModuleInfoProvider getReactModuleInfoProvider() {
+    return () -> {
+      Map<String, ReactModuleInfo> moduleInfos = new HashMap<>();
+      boolean isTurboModule = BuildConfig.IS_NEW_ARCHITECTURE_ENABLED;
+
+      moduleInfos.put(
+          NativeAndroidOverlaySpec.NAME,
+          new ReactModuleInfo(
+              NativeAndroidOverlaySpec.NAME,
+              NativeAndroidOverlaySpec.NAME,
+              false,
+              false,
+              false,
+              isTurboModule));
+      return moduleInfos;
+    };
+  }
+
+  @NonNull
+  @Override
+  public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext reactContext) {
+    return Collections.emptyList();
+  }
+}

package/android/src/main/java/tech/zmario/androidoverlay/module/OverlayModule.java

@@ -0,0 +1,133 @@
+package tech.zmario.androidoverlay.module;
+
+import android.content.Intent;
+import android.net.Uri;
+import android.os.Build;
+import android.provider.Settings;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.bridge.ReadableMap;
+import tech.zmario.androidoverlay.NativeAndroidOverlaySpec;
+import tech.zmario.androidoverlay.service.OverlayService;
+
+public class OverlayModule extends NativeAndroidOverlaySpec {
+
+  public OverlayModule(ReactApplicationContext reactContext) {
+    super(reactContext);
+  }
+
+  @ReactMethod
+  public void hasPermission(Promise promise) {
+    promise.resolve(Settings.canDrawOverlays(getReactApplicationContext()));
+  }
+
+  @ReactMethod
+  public void requestPermission() {
+    if (!Settings.canDrawOverlays(getReactApplicationContext())) {
+      Intent intent =
+          new Intent(
+              Settings.ACTION_MANAGE_OVERLAY_PERMISSION,
+              Uri.parse("package:" + getReactApplicationContext().getPackageName()));
+      intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+      getReactApplicationContext().startActivity(intent);
+    }
+  }
+
+  @ReactMethod
+  public void startOverlay(String componentName, ReadableMap options) {
+    if (!Settings.canDrawOverlays(getReactApplicationContext())) {
+      return;
+    }
+    Intent intent = new Intent(getReactApplicationContext(), OverlayService.class);
+    intent.putExtra("componentName", componentName);
+
+    if (options != null) {
+      if (options.hasKey("width")) intent.putExtra("width", options.getDouble("width"));
+      if (options.hasKey("height")) intent.putExtra("height", options.getDouble("height"));
+      if (options.hasKey("x")) intent.putExtra("x", options.getDouble("x"));
+      if (options.hasKey("y")) intent.putExtra("y", options.getDouble("y"));
+      if (options.hasKey("gravity")) intent.putExtra("gravity", options.getString("gravity"));
+
+      if (options.hasKey("draggable"))
+        intent.putExtra("draggable", options.getBoolean("draggable"));
+
+      if (options.hasKey("touchable"))
+        intent.putExtra("touchable", options.getBoolean("touchable"));
+
+      if (options.hasKey("focusable"))
+        intent.putExtra("focusable", options.getBoolean("focusable"));
+
+      if (options.hasKey("notificationTitle"))
+        intent.putExtra("notificationTitle", options.getString("notificationTitle"));
+
+      if (options.hasKey("notificationText"))
+        intent.putExtra("notificationText", options.getString("notificationText"));
+
+      if (options.hasKey("notificationIcon"))
+        intent.putExtra("notificationIcon", options.getString("notificationIcon"));
+
+      if (options.hasKey("channelId")) intent.putExtra("channelId", options.getString("channelId"));
+
+      if (options.hasKey("channelName"))
+        intent.putExtra("channelName", options.getString("channelName"));
+
+      if (options.hasKey("foreground"))
+        intent.putExtra("foreground", options.getBoolean("foreground"));
+    }
+
+    boolean foreground = true;
+
+    if (options != null && options.hasKey("foreground")) {
+      foreground = options.getBoolean("foreground");
+    }
+
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && foreground) {
+      getReactApplicationContext().startForegroundService(intent);
+    } else {
+      getReactApplicationContext().startService(intent);
+    }
+  }
+
+  @ReactMethod
+  public void stopOverlay(String componentName) {
+    if (OverlayService.getInstance() != null) {
+      OverlayService.getInstance().stopOverlayInstance(componentName);
+    }
+  }
+
+  @ReactMethod
+  public void resizeOverlay(double width, double height, String componentName) {
+    float density = getReactApplicationContext().getResources().getDisplayMetrics().density;
+    int pxWidth = (int) (width * density);
+    int pxHeight = (int) (height * density);
+
+    if (OverlayService.getInstance() != null) {
+      OverlayService.getInstance().resizeOverlay(componentName, pxWidth, pxHeight);
+    }
+  }
+
+  @ReactMethod
+  public void startMove(String componentName) {
+    if (OverlayService.getInstance() != null) {
+      OverlayService.getInstance().startMove(componentName);
+    }
+  }
+
+  @ReactMethod
+  public void moveOverlay(double dx, double dy, String componentName) {
+    float density = getReactApplicationContext().getResources().getDisplayMetrics().density;
+
+    if (OverlayService.getInstance() != null) {
+      OverlayService.getInstance()
+          .moveOverlay(componentName, (int) (dx * density), (int) (dy * density));
+    }
+  }
+
+  @ReactMethod
+  public void commitMove(String componentName) {
+    if (OverlayService.getInstance() != null) {
+      OverlayService.getInstance().commitMove(componentName);
+    }
+  }
+}

package/android/src/main/java/tech/zmario/androidoverlay/service/OverlayInstance.java

@@ -0,0 +1,41 @@
+package tech.zmario.androidoverlay.service;
+
+import android.widget.FrameLayout;
+import com.facebook.react.interfaces.fabric.ReactSurface;
+
+public class OverlayInstance {
+
+  private final FrameLayout overlayView;
+  private final ReactSurface reactSurface;
+  private int initialX = 0;
+  private int initialY = 0;
+
+  public OverlayInstance(FrameLayout overlayView, ReactSurface reactSurface) {
+    this.overlayView = overlayView;
+    this.reactSurface = reactSurface;
+  }
+
+  public FrameLayout getOverlayView() {
+    return overlayView;
+  }
+
+  public ReactSurface getReactSurface() {
+    return reactSurface;
+  }
+
+  public int getInitialX() {
+    return initialX;
+  }
+
+  public void setInitialX(int initialX) {
+    this.initialX = initialX;
+  }
+
+  public int getInitialY() {
+    return initialY;
+  }
+
+  public void setInitialY(int initialY) {
+    this.initialY = initialY;
+  }
+}

package/android/src/main/java/tech/zmario/androidoverlay/service/OverlayLayoutParamsBuilder.java

@@ -0,0 +1,57 @@
+package tech.zmario.androidoverlay.service;
+
+import android.graphics.PixelFormat;
+import android.os.Build;
+import android.view.Gravity;
+import android.view.WindowManager;
+
+public class OverlayLayoutParamsBuilder {
+
+  private OverlayLayoutParamsBuilder() {}
+
+  public static WindowManager.LayoutParams build(
+      double width,
+      double height,
+      double x,
+      double y,
+      String gravity,
+      boolean focusable,
+      boolean touchable,
+      float density,
+      int screenWidth) {
+    int layoutFlag =
+        Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
+            ? WindowManager.LayoutParams.TYPE_APPLICATION_OVERLAY
+            : WindowManager.LayoutParams.TYPE_PHONE;
+    int widthPx = width > 0 ? (int) (width * density) : (int) (screenWidth * 0.95);
+    int heightPx = height > 0 ? (int) (height * density) : (int) (140f * density);
+
+    int flags = WindowManager.LayoutParams.FLAG_LAYOUT_NO_LIMITS;
+
+    if (focusable) {
+      flags |= WindowManager.LayoutParams.FLAG_NOT_TOUCH_MODAL;
+    } else {
+      flags |= WindowManager.LayoutParams.FLAG_NOT_FOCUSABLE;
+    }
+    if (!touchable) {
+      flags |= WindowManager.LayoutParams.FLAG_NOT_TOUCHABLE;
+    }
+
+    WindowManager.LayoutParams params =
+        new WindowManager.LayoutParams(
+            widthPx, heightPx, layoutFlag, flags, PixelFormat.TRANSLUCENT);
+
+    int gravityFlag = Gravity.BOTTOM | Gravity.CENTER_HORIZONTAL;
+    if ("top".equalsIgnoreCase(gravity)) {
+      gravityFlag = Gravity.TOP | Gravity.CENTER_HORIZONTAL;
+    } else if ("center".equalsIgnoreCase(gravity)) {
+      gravityFlag = Gravity.CENTER;
+    }
+
+    params.gravity = gravityFlag;
+    params.x = (int) (x * density);
+    params.y = (int) (y * density);
+
+    return params;
+  }
+}