rn-mrz-capture-scanner

rn-mrz-capture-scanner is an Expo React Native native module for scanning the Machine Readable Zone (MRZ) on passports and identity cards.

It can return either:

• the raw MRZ text; or
• the raw MRZ text plus a high-resolution cropped JPEG of the passport data page.

| Platform | OCR engine | | --- | --- | | iOS | Apple Vision | | Android | Google ML Kit Text Recognition |

Supported MRZ layouts:

• TD1 identity cards: 3 lines of 30 characters
• TD3 passports: 2 lines of 44 characters

How it works

1. scanMRZ() opens a native full-screen camera scanner.
2. The user places the document inside the on-screen guide.
3. Apple Vision or Google ML Kit reads each camera frame.
4. The scanner filters possible MRZ lines and waits until the same result is stable across multiple frames.
5. If captureImage is enabled, the scanner takes a full-resolution still photo after recognition, maps the visible ICAO TD3 passport guide back to that image, crops the data page, and saves it as a JPEG at 95% quality. It falls back to the recognition frame if iOS cannot add a still-photo output.
6. The scanner closes and resolves the promise.

The package returns raw MRZ text. It does not parse passport fields or perform application-level checks such as expiration validation. Use an MRZ parser separately when your application needs structured data.

Installation

npx expo install rn-mrz-capture-scanner

Add the config plugin to app.json or app.config.ts:

{
  "expo": {
    "plugins": [
      [
        "rn-mrz-capture-scanner",
        {
          "cameraPermissionText": "Allow this app to scan your passport."
        }
      ]
    ]
  }
}

The plugin adds:

• NSCameraUsageDescription on iOS
• android.permission.CAMERA on Android

The plugin keeps an existing iOS camera permission description if the app already defines one.

Build the app

This package contains native iOS and Android code. It does not work in Expo Go.

After installing it or changing its config, create a new native build:

npx expo prebuild
npx expo run:android

On macOS, iOS can be built locally:

npx expo run:ios

From Windows or Linux, use EAS Build for iOS:

eas build --platform ios

A Metro reload or JavaScript-only update cannot add this native module to an existing app binary.

Capture MRZ and document image

Set captureImage: true when both values are required:

import { scanMRZ, type MRZScanResult } from 'rn-mrz-capture-scanner';

const result: MRZScanResult = await scanMRZ({
  captureImage: true,
  instructionText: 'Place the passport information page inside the frame',
  isChipShow: false,
});

// result.mrz is the raw MRZ string.
// result.imageUri is a local file:// URI for the cropped JPEG.

Result shape:

type MRZScanResult = {
  mrz: string;
  imageUri: string;
};

The image contains the passport data page shown inside the scanner guide, not the complete camera frame. The guide uses the ICAO TD3 page ratio of 125 x 88 mm so the portrait, printed fields, and both MRZ lines remain in the result.

Scan MRZ text only

Image capture is disabled by default. The compatibility API returns a string:

import { scanMRZ } from 'rn-mrz-capture-scanner';

const mrz = await scanMRZ();
// "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<\nL898902C36UTO7408122F1204159ZE184226B<<<<<10"

Custom UI options can still be used without capturing an image:

const mrz = await scanMRZ({
  instructionText: 'Place the back of your ID inside the frame',
  isChipShow: true,
});

React component example

import { useState } from 'react';
import { Alert, Button, Image, View } from 'react-native';
import { scanMRZ, type MRZScanResult } from 'rn-mrz-capture-scanner';

type ScannerError = Error & { code?: string };

export function PassportScanner() {
  const [scan, setScan] = useState<MRZScanResult | null>(null);
  const [scanning, setScanning] = useState(false);

  const handleScan = async () => {
    if (scanning) return;

    setScanning(true);

    try {
      const result = await scanMRZ({
        captureImage: true,
        instructionText: 'Place the passport information page inside the frame',
        isChipShow: false,
      });

      setScan(result);
      // Parse result.mrz and copy or upload result.imageUri here.
    } catch (error) {
      const scannerError = error as ScannerError;

      if (scannerError.code !== 'ERR_CANCELLED') {
        Alert.alert('Scan failed', scannerError.message);
      }
    } finally {
      setScanning(false);
    }
  };

  return (
    <View>
      <Button
        title={scanning ? 'Scanning…' : 'Scan passport'}
        disabled={scanning}
        onPress={handleScan}
      />

      {scan ? (
        <Image
          source={{ uri: scan.imageUri }}
          style={{ width: 320, height: 200 }}
          resizeMode="contain"
        />
      ) : null}
    </View>
  );
}

Do not log result.mrz or other passport data in production.

API

scanMRZ(options?)

Opens the scanner and returns a promise.

| Option | Type | Default | Description | | --- | --- | --- | --- | | instructionText | string | Package message | Text displayed above the scanner guide. | | isChipShow | boolean | true | Shows or hides the document chip illustration. | | captureImage | boolean | false | Captures a high-resolution JPEG cropped to the TD3 passport guide. |

Return type depends on captureImage:

scanMRZ({ captureImage: true }): Promise<MRZScanResult>;
scanMRZ(): Promise<string>;

MRZ lines in the returned string are separated by \n.

Errors and cancellation

Wrap calls in try/catch. Native failures expose a code and message.

| Code | Platform | Meaning | | --- | --- | --- | | ERR_CANCELLED | iOS, Android | The user closed the scanner. Android also currently uses this code when its scanner activity exits after permission, camera, or image-capture failure; inspect the message. | | ERR_NO_ACTIVITY | Android | No current Android activity was available to open the scanner. | | ERR_UI | iOS | No active view controller was available to present the scanner. | | ERR_MRZ | Android | The scanner finished without a usable MRZ value. |

Example:

try {
  const mrz = await scanMRZ();
} catch (error) {
  const scannerError = error as Error & { code?: string };

  if (scannerError.code === 'ERR_CANCELLED') {
    return;
  }

  throw error;
}

Image lifetime

Captured files use temporary storage:

• Android: application cache directory
• iOS: application temporary directory

The operating system may delete these files. Treat imageUri as short-lived:

1. Receive the scan result.
2. Parse and validate the MRZ if required.
3. Upload the JPEG or copy it to persistent app storage.
4. Remove any copied file when the application flow ends.

Do not store the URI and assume it will still work after an app restart or a long delay.

Privacy and security

MRZ values and identity-document images contain sensitive personal data.

• Never log raw MRZ text, parsed document fields, or image URIs in production.
• Never put passport data in analytics, crash-report metadata, or notification text.
• Upload images only through an authenticated and encrypted application flow.
• Keep temporary data only as long as the user flow requires it.
• Clear application state after submission or cancellation.

Requirements

• Expo SDK 49 or newer
• React 18 or newer
• React Native 0.72 or newer
• iOS 15.1 or newer
• Android device supported by CameraX
• A development or production build, not Expo Go

Real-device testing is strongly recommended. Test glare, blur, low light, rotation, permission denial, cancellation, invalid MRZ text, repeated scans, crop alignment, and image upload.

Credits

Based on rn-mrz-scanner by Berkay Aslan, licensed under MIT.

License

MIT