by nStudio | v2.0.2
A Passport/MRZ reader for NativeScript
npm i --save @nstudio/nativescript-xavier-passport

NativeScript Xavier Passport

NativeScript plugin to scan MRZ data from Passports and Cards for Android and iOS.

npm npm stars forks license

nStudio banner

Do you need assistance on your project or plugin? Contact the nStudio team anytime at team@nstudio.io to get up to speed with the best practices in mobile and web app development.

NativeScript Xavier-Passport

This is a NativeScript cross platform plugin wrapping the Black Shark Tech Xavier library for IOS and Android.


Our code is 2018-2019, nStudio, LLC. Everything is LICENSED under the APACHE 2.0 License, meaning you are free to include this in any type of program.

However, the base Xavier library must be licensed from them see: https://github.com/BlackSharkTech/Xavier-demo-android and https://github.com/BlackSharkTech/Xavier-demo-ios To get a real license key you need to contact sales @ blacksharktech.com


Same plugin works on NativeScript 5.x and above

Run tns plugin add @nstudio/nativescript-xavier-passport in your ROOT directory of your project.

Android Required Setup

In your app/App_Resources/Android/src/main/res/AndroidManifest.xml you need to do the following:

  1. Add xmlns:tools="http://schemas.android.com/tools" to the <Manifest ...
  2. Int the <application add tools:replace="android:allowBackup"
    Files 3a. In the <uses-sdk change the android:minSdkVersion="XX" to at least 21. 3b. If you are using a newer version of NativeScript and your file does NOT have a <uses-sdk; then you need to change the app/App_Resources/Android/app.gradle file. Change minSdkVersion to at least 21


Start Scanning

const Passport = require('@nstudio/nativescript-xavier-passport');

const zp = new Passport({"licenseKey": "<LICENSE_KEY>"});
zp.on("results", function(results) { console.log("Results:", results); });

Instantiating the Passport Object

new Password(options)


  • licenseKey = Your license key (Can be any string for Testing!)
  • boundingBoxSearchingColor = Color of the bounding box
  • boundingBoxFoundColor = Color of the bounding box when found
  • closeButtonColor = Close button color
  • flashOnButtonColor = Flash on button color
  • flashOffButtonColor = Flash off button color
  • flashButtonEnabled = (true/false) Display the flash button
  • instructionTextEnabled = (true/false) Display instructional text in camera
  • instructionText = Text to display
  • instructionTextColor = Text color
  • instructionTextFont = Font to use
  • cameraNegativeSpaceBackgroundEnabled = Background space
  • cameraNegativeSpaceBackgroundColor = Background color


Will enable more logs to be output to the log system.


Might be required for iOS; last version of MRZ had issue with notification of closing; so we have a work around...



Start the scanning


zp.on("error", function(error) { console.log("Error", error); });
zp.on("closed", function() { console.log("Closed the reader"); });
zp.on("results", function(results) { console.log("Results", results); });
  • results - Will give you an object with keys for everything including the raw data as the "rawMrz" key.
  • error - Will give you the error message from Xavier or if your results or close event code is buggy then the error from your code will be also passed back via this callback.
  • closed - Will be triggered when it closes the scanning screen. (on iOS this is triggered several times)

Result Object:

  • documentImage - The image of the identity; this is either a native iOS image or Android Bitmap. You can assign it to a ImageSource using the fromNativeSource() function.

  • documentType - The document type.

  • countryCitizen - The code of the country/nationality of identity

  • givenName - The given/first name of the identity.

  • surname - The surname/last/family name

  • documentNumber - The document number identity.

  • countryIssue - The issuing country code

  • dateBirth - Date of Birth; Returned in YYMMDD format

  • sex - gender of identity.

  • dateExpiration - Expiration date of identity in YYMMDD format

  • optionalData - The optional data for a second line in a MRZ

  • optionalData2 - The optional data for a thrid line in a MRZ

  • stateIssue - Issuing state

  • rawMrz - The unparsed MRZ read

  • documentNumberCheckDigit - The check digit for the document number.

  • dateBirthCheckDigit - The check digit for the date of birth

  • dateExpirationCheckDigit - The check digit for the expiration date.

  • optionalDataCheckDigit - The check digit for the optional data

  • compositeCheckDigit - The check digit over the document number, birth date, expiration date, optional data, and their check digits


Please see the demo source (See: main-view-model.js).