react-native-subject-lift

Bring Select Subject–style interactions into React Native: iOS uses VisionKit (same stack as Photos), Android uses ML Kit segmentation plus a Reanimated lift animation.

| | iOS 16+ | Android 7+ (API 24+) | |---|:---:|:---:| | Engine | VisionKit ImageAnalysisInteraction | ML Kit Subject Segmenter | | UX | System lift, Live Text, Visual Look Up | Custom lift animation |

Install

npm install react-native-subject-lift

iOS — cd ios && pod install. Deployment target 16.0.

Android — add to android/app/build.gradle:

dependencies {
  implementation 'com.google.android.gms:play-services-mlkit-subject-segmentation:16.0.0-beta1'
}

react-native-reanimated ≥ 3 is a peer dependency (used on Android).

Quick start

import { SubjectLiftView, useSubjectLift } from 'react-native-subject-lift';

export function PhotoScreen({ imageUri }: { imageUri: string }) {
  const { isReady, status, handleAnalysisComplete } = useSubjectLift();

  return (
    <SubjectLiftView
      imageUri={imageUri}
      style={{ flex: 1 }}
      onAnalysisComplete={handleAnalysisComplete}
      onSubjectLifted={({ nativeEvent }) => {
        // nativeEvent.type + nativeEvent.data — see below
      }}
    />
  );
}

iOS — preferredInteractionTypes

• automatic (default) — subject lift, Live Text, Visual Look Up, QR/barcode detection.
• subjectLiftOnly — subject lift only.

API

| Prop | Description | |------|-------------| | imageUri | file:// or https:// image URI | | preferredInteractionTypes | iOS only — see above | | onAnalysisComplete | Analysis finished (ready / error; Android may include base64 preview) | | onSubjectLifted | Optional — gesture / cutout / text payloads (see src/types.ts) | | style | ViewStyle |

useSubjectLift()

Returns status, isReady, error, maskedBase64 (Android), handleAnalysisComplete, and reset.

onSubjectLifted (iOS)

Shape: { nativeEvent: { type: string, data: string } }. Full detail is in the SubjectLiftedEvent JSDoc in src/types.ts.

• image — JSON when a lift gesture starts; base64 PNG when the subject cutout is ready (timing varies; VisionKit does not guarantee a bitmap at gesture start).
• text — iOS 17+: JSON selectionBegan with selected text when selection first has content; plain string when the selection ends.
• dataDetector / interaction — began-phase JSON for other interaction kinds.
• QR/barcodes — detected in analysis and shown in system Live Text / data-detector UI; there is no separate “QR subject lift” bitmap event.

On Android, onSubjectLifted fires with type: "image" and base64 when segmentation succeeds.

Notes

• Subject lift on iOS is meant for real devices (A12+); the Simulator is often unreliable.
• Use photos with a clear foreground subject; not every image will segment.
• Remote HTTP images need appropriate App Transport Security on iOS.

Requirements

React Native ≥ 0.72 · iOS 16+ · Android minSdk 24 · Reanimated ≥ 3 (Android)

License

MIT © Berkay Baygut