@capacitor-mlkit/barcode-scanning

Unofficial Capacitor plugin for ML Kit Barcode Scanning.[^1][^2]

Features

• 🧩 Optional ready-to-use interface without webview customizations
• 🏎️ Extremely fast
• 📷 Scan multiple barcodes at once
• ⏺️ Define detection area
• 🏞️ Reading barcodes from images
• 🔦 Torch and Autofocus support
• 🔋 Supports Android and iOS

For a complete list of supported barcodes, see BarcodeFormat.

Demo

A working example can be found here: https://github.com/robingenz/capacitor-mlkit-plugin-demo

| Android | | ------------------------------------------------------------------------------------------------------------------------------- | | |

Guides

• How to build an Ionic Barcode Scanner with Capacitor

Installation

npm install @capacitor-mlkit/barcode-scanning
npx cap sync

Android

Permissions

This API requires the following permissions be added to your AndroidManifest.xml before the application tag:

<!-- To get access to the camera. -->
<uses-permission android:name="android.permission.CAMERA" />
<!-- To get access to the flashlight. -->
<uses-permission android:name="android.permission.FLASHLIGHT"/>

You also need to add the following meta data in the application tag in your AndroidManifest.xml:

<meta-data android:name="com.google.mlkit.vision.DEPENDENCIES" android:value="barcode_ui"/>
<!-- To use multiple models: android:value="face,model2,model3" -->

Data Binding

Enable the databinding library by setting the dataBinding and enabled build options to true in your module-level (app-level) Gradle file (usually android/app/build.gradle):

android {
    ...
+    buildFeatures {
+        dataBinding true
+    }
+    dataBinding {
+        enabled = true
+    }
}

Variables

This plugin will use the following project variables (defined in your app’s variables.gradle file):

• $androidxCameraCamera2Version version of com.google.mlkit:barcode-scanning (default: 1.1.0)
• $androidxCameraCoreVersion version of com.google.mlkit:barcode-scanning (default: 1.1.0)
• $androidxCameraLifecycleVersion version of com.google.mlkit:barcode-scanning (default: 1.1.0)
• $androidxCameraViewVersion version of com.google.mlkit:barcode-scanning (default: 1.1.0)
• $mlkitBarcodeScanningVersion version of com.google.mlkit:barcode-scanning (default: 17.1.0)
• $playServicesCodeScannerVersion version of com.google.mlkit:barcode-scanning (default: 16.0.0)

iOS

Add the NSCameraUsageDescription key to the ios/App/App/Info.plist file, which tells the user why the app needs to use the camera:

+ <key>NSCameraUsageDescription</key>
+ <string>The app enables the scanning of various barcodes.</string>

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-mlkit-plugin-demo

Usage

import {
  BarcodeScanner,
  BarcodeFormat,
  LensFacing,
} from '@capacitor-mlkit/barcode-scanning';

const startScan = async () => {
  // The camera is visible behind the WebView, so that you can customize the UI in the WebView.
  // However, this means that you have to hide all elements that should not be visible.
  // You can find an example in our demo repository.
  // In this case we set a class `barcode-scanner-active`, which then contains certain CSS rules for our app.
  document.querySelector('body')?.classList.add('barcode-scanner-active');

  // Add the `barcodeScanned` listener
  const listener = await BarcodeScanner.addListener(
    'barcodeScanned',
    async result => {
      console.log(result.barcode);
    },
  );

  // Start the barcode scanner
  await BarcodeScanner.startScan();
};

const stopScan = async () => {
  // Make all elements in the WebView visible again
  document.querySelector('body')?.classList.remove('barcode-scanner-active');

  // Remove all listeners
  await BarcodeScanner.removeAllListeners();

  // Stop the barcode scanner
  await BarcodeScanner.stopScan();
};

const scanSingleBarcode = async () => {
  return new Promise(async resolve => {
    document.querySelector('body')?.classList.add('barcode-scanner-active');

    const listener = await BarcodeScanner.addListener(
      'barcodeScanned',
      async result => {
        await listener.remove();
        document
          .querySelector('body')
          ?.classList.remove('barcode-scanner-active');
        await BarcodeScanner.stopScan();
        resolve(result.barcode);
      },
    );

    await BarcodeScanner.startScan();
  });
};

const scan = async () => {
  const { barcodes } = await BarcodeScanner.scan({
    formats: [BarcodeFormat.QrCode],
  });
  return barcodes;
};

const isSupported = async () => {
  const { supported } = await BarcodeScanner.isSupported();
  return supported;
};

const enableTorch = async () => {
  await BarcodeScanner.enableTorch();
};

const disableTorch = async () => {
  await BarcodeScanner.disableTorch();
};

const toggleTorch = async () => {
  await BarcodeScanner.toggleTorch();
};

const isTorchEnabled = async () => {
  const { enabled } = await BarcodeScanner.isTorchEnabled();
  return enabled;
};

const isTorchAvailable = async () => {
  const { available } = await BarcodeScanner.isTorchAvailable();
  return available;
};

const setZoomRatio = async () => {
  await BarcodeScanner.setZoomRatio({ zoomRatio: 0.5 });
};

const getZoomRatio = async () => {
  const { zoomRatio } = await BarcodeScanner.getZoomRatio();
  return zoomRatio;
};

const getMinZoomRatio = async () => {
  const { zoomRatio } = await BarcodeScanner.getMinZoomRatio();
  return zoomRatio;
};

const getMaxZoomRatio = async () => {
  const { zoomRatio } = await BarcodeScanner.getMaxZoomRatio();
  return zoomRatio;
};

const openSettings = async () => {
  await BarcodeScanner.openSettings();
};

const isGoogleBarcodeScannerModuleAvailable = async () => {
  const { available } =
    await BarcodeScanner.isGoogleBarcodeScannerModuleAvailable();
  return available;
};

const installGoogleBarcodeScannerModule = async () => {
  await BarcodeScanner.installGoogleBarcodeScannerModule();
};

const checkPermissions = async () => {
  const { camera } = await BarcodeScanner.checkPermissions();
  return camera;
};

const requestPermissions = async () => {
  const { camera } = await BarcodeScanner.requestPermissions();
  return camera;
};

An example of the CSS class barcode-scanner-active with Ionic Framework could be:

// Hide all elements
body.barcode-scanner-active {
  visibility: hidden;
  --background: transparent;
  --ion-background-color: transparent;
}

// Show only the barcode scanner modal
.barcode-scanner-modal {
  visibility: visible;
}

@media (prefers-color-scheme: dark) {
  .barcode-scanner-modal {
    --background: transparent;
    --ion-background-color: transparent;
  }
}

An example of the CSS class barcode-scanner-active without Ionic Framework could be:

// Hide all elements
body.barcode-scanner-active {
  visibility: hidden;
}

// Show only the barcode scanner modal
.barcode-scanner-modal {
  visibility: visible;
}

If you can't see the camera view, make sure all elements in the DOM are not visible or have a transparent background to debug the issue.

API

• startScan(...)
• stopScan()
• readBarcodesFromImage(...)
• scan(...)
• isSupported()
• enableTorch()
• disableTorch()
• toggleTorch()
• isTorchEnabled()
• isTorchAvailable()
• setZoomRatio(...)
• getZoomRatio()
• getMinZoomRatio()
• getMaxZoomRatio()
• openSettings()
• isGoogleBarcodeScannerModuleAvailable()
• installGoogleBarcodeScannerModule()
• checkPermissions()
• requestPermissions()
• addListener('barcodeScanned', ...)
• addListener('scanError', ...)
• addListener('googleBarcodeScannerModuleInstallProgress', ...)
• removeAllListeners()
• Interfaces
• Type Aliases
• Enums

startScan(...)

startScan(options?: StartScanOptions | undefined) => Promise<void>

Start scanning for barcodes.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | StartScanOptions |

Since: 0.0.1

stopScan()

stopScan() => Promise<void>

Stop scanning for barcodes.

Only available on Android and iOS.

Since: 0.0.1

readBarcodesFromImage(...)

readBarcodesFromImage(options: ReadBarcodesFromImageOptions) => Promise<ReadBarcodesFromImageResult>

Read barcodes from an image.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------- | | options | ReadBarcodesFromImageOptions |

Returns: Promise<ReadBarcodesFromImageResult>

Since: 0.0.1

scan(...)

scan(options?: ScanOptions | undefined) => Promise<ScanResult>

Scan a barcode with a ready-to-use interface without WebView customization.

On Android, this method is only available on devices with Google Play Services installed. Therefore, no camera permission is required.

Attention: Before using this method on Android, first check if the Google Barcode Scanner module is available by using isGoogleBarcodeScannerModuleAvailable().

Only available on Android and iOS.

| Param | Type | | ------------- | --------------------------------------------------- | | options | ScanOptions |

Returns: Promise<ScanResult>

Since: 0.0.1

isSupported()

isSupported() => Promise<IsSupportedResult>

Returns whether or not the barcode scanner is supported.

Available on Android and iOS.

Returns: Promise<IsSupportedResult>

Since: 0.0.1

enableTorch()

enableTorch() => Promise<void>

Enable camera's torch (flash) during a scan session.

Only available on Android and iOS.

Since: 0.0.1

disableTorch()

disableTorch() => Promise<void>

Disable camera's torch (flash) during a scan session.

Only available on Android and iOS.

Since: 0.0.1

toggleTorch()

toggleTorch() => Promise<void>

Toggle camera's torch (flash) during a scan session.

Only available on Android and iOS.

Since: 0.0.1

isTorchEnabled()

isTorchEnabled() => Promise<IsTorchEnabledResult>

Returns whether or not the camera's torch (flash) is enabled.

Only available on Android and iOS.

Returns: Promise<IsTorchEnabledResult>

Since: 0.0.1

isTorchAvailable()

isTorchAvailable() => Promise<IsTorchAvailableResult>

Returns whether or not the camera's torch (flash) is available.

Only available on Android and iOS.

Returns: Promise<IsTorchAvailableResult>

Since: 0.0.1

setZoomRatio(...)

setZoomRatio(options: SetZoomRatioOptions) => Promise<void>

Set the zoom ratio of the camera.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | SetZoomRatioOptions |

Since: 5.4.0

getZoomRatio()

getZoomRatio() => Promise<GetZoomRatioResult>

Get the zoom ratio of the camera.

Only available on Android and iOS.

Returns: Promise<GetZoomRatioResult>

Since: 5.4.0

getMinZoomRatio()

getMinZoomRatio() => Promise<GetMinZoomRatioResult>

Get the minimum zoom ratio of the camera.

Only available on Android and iOS.

Returns: Promise<GetMinZoomRatioResult>

Since: 5.4.0

getMaxZoomRatio()

getMaxZoomRatio() => Promise<GetMaxZoomRatioResult>

Get the maximum zoom ratio of the camera.

Only available on Android and iOS.

Returns: Promise<GetMaxZoomRatioResult>

Since: 5.4.0

openSettings()

openSettings() => Promise<void>

Open the settings of the app so that the user can grant the camera permission.

Only available on Android and iOS.

Since: 0.0.1

isGoogleBarcodeScannerModuleAvailable()

isGoogleBarcodeScannerModuleAvailable() => Promise<IsGoogleBarcodeScannerModuleAvailableResult>

Check if the Google Barcode Scanner module is available.

If the Google Barcode Scanner module is not available, you can install it by using installGoogleBarcodeScannerModule().

Only available on Android.

Returns: Promise<IsGoogleBarcodeScannerModuleAvailableResult>

Since: 5.1.0

installGoogleBarcodeScannerModule()

installGoogleBarcodeScannerModule() => Promise<void>

Install the Google Barcode Scanner module.

Attention: This only starts the installation. The googleBarcodeScannerModuleInstallProgress event listener will notify you when the installation is complete.

Only available on Android.

Since: 5.1.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check camera permission.

Only available on Android and iOS.

Returns: Promise<PermissionStatus>

Since: 0.0.1

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request camera permission.

Only available on Android and iOS.

Returns: Promise<PermissionStatus>

Since: 0.0.1

addListener('barcodeScanned', ...)

addListener(eventName: 'barcodeScanned', listenerFunc: (event: BarcodeScannedEvent) => void) => Promise<PluginListenerHandle>

Called when a barcode is scanned.

Available on Android and iOS.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------- | | eventName | 'barcodeScanned' | | listenerFunc | (event: BarcodeScannedEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('scanError', ...)

addListener(eventName: 'scanError', listenerFunc: (event: ScanErrorEvent) => void) => Promise<PluginListenerHandle>

Called when an error occurs during the scan.

Available on Android and iOS.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------- | | eventName | 'scanError' | | listenerFunc | (event: ScanErrorEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('googleBarcodeScannerModuleInstallProgress', ...)

addListener(eventName: 'googleBarcodeScannerModuleInstallProgress', listenerFunc: (event: GoogleBarcodeScannerModuleInstallProgressEvent) => void) => Promise<PluginListenerHandle>

Called when the Google Barcode Scanner module is installed.

Available on Android.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | eventName | 'googleBarcodeScannerModuleInstallProgress' | | listenerFunc | (event: GoogleBarcodeScannerModuleInstallProgressEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 5.1.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.0.1

Interfaces

StartScanOptions

| Prop | Type | Description | Since | | ---------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----- | | formats | BarcodeFormat[] | Improve the speed of the barcode scanner by configuring the barcode formats to scan for. | 0.0.1 | | lensFacing | LensFacing | Configure the camera (front or back) to use. | 0.0.1 |

ReadBarcodesFromImageResult

| Prop | Type | Description | Since | | -------------- | ---------------------- | ---------------------- | ----- | | barcodes | Barcode[] | The detected barcodes. | 0.0.1 |

Barcode

| Prop | Type | Description | Since | | ------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | bytes | number[] | Raw bytes as it was encoded in the barcode. | 0.0.1 | | cornerPoints | [[number, number], [number, number], [number, number], [number, number]] | The four corner points of the barcode in clockwise order starting with top-left. This property is currently only supported by the startScan(...) method. | 0.0.1 | | displayValue | string | The barcode value in a human readable format. | 0.0.1 | | format | BarcodeFormat | The barcode format. | 0.0.1 | | rawValue | string | The barcode value in a machine readable format. | 0.0.1 | | valueType | BarcodeValueType | The barcode value type. | 0.0.1 |

ReadBarcodesFromImageOptions

| Prop | Type | Description | Since | | ------------- | ---------------------------- | ---------------------------------------------------------------------------------------- | ----- | | formats | BarcodeFormat[] | Improve the speed of the barcode scanner by configuring the barcode formats to scan for. | 0.0.1 | | path | string | The local path to the image file. | 0.0.1 |

ScanResult

| Prop | Type | Description | Since | | -------------- | ---------------------- | ---------------------- | ----- | | barcodes | Barcode[] | The detected barcodes. | 0.0.1 |

ScanOptions

| Prop | Type | Description | Since | | ------------- | ---------------------------- | ---------------------------------------------------------------------------------------- | ----- | | formats | BarcodeFormat[] | Improve the speed of the barcode scanner by configuring the barcode formats to scan for. | 0.0.1 |

IsSupportedResult

| Prop | Type | Description | Since | | --------------- | -------------------- | --------------------------------------------------------------------------------------- | ----- | | supported | boolean | Whether or not the barcode scanner is supported by checking if the device has a camera. | 0.0.1 |

IsTorchEnabledResult

| Prop | Type | Description | Since | | ------------- | -------------------- | ------------------------------------ | ----- | | enabled | boolean | Whether or not the torch is enabled. | 0.0.1 |

IsTorchAvailableResult

| Prop | Type | Description | Since | | --------------- | -------------------- | -------------------------------------- | ----- | | available | boolean | Whether or not the torch is available. | 0.0.1 |

SetZoomRatioOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | ---------------------- | ----- | | zoomRatio | number | The zoom ratio to set. | 5.4.0 |

GetZoomRatioResult

| Prop | Type | Description | Since | | --------------- | ------------------- | --------------- | ----- | | zoomRatio | number | The zoom ratio. | 5.4.0 |

GetMinZoomRatioResult

| Prop | Type | Description | Since | | --------------- | ------------------- | ----------------------- | ----- | | zoomRatio | number | The minimum zoom ratio. | 5.4.0 |

GetMaxZoomRatioResult

| Prop | Type | Description | Since | | --------------- | ------------------- | ----------------------- | ----- | | zoomRatio | number | The maximum zoom ratio. | 5.4.0 |

IsGoogleBarcodeScannerModuleAvailableResult

| Prop | Type | Description | Since | | --------------- | -------------------- | ------------------------------------------------------------------------------------- | ----- | | available | boolean | Whether or not the Google Barcode Scanner module is available. | 5.1.0 |

PermissionStatus

| Prop | Type | Since | | ------------ | ----------------------------------------------------------------------- | ----- | | camera | CameraPermissionState | 0.0.1 |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

BarcodeScannedEvent

| Prop | Type | Description | Since | | ------------- | ------------------------------------------- | ------------------- | ----- | | barcode | Barcode | A detected barcode. | 0.0.1 |

ScanErrorEvent

| Prop | Type | Description | Since | | ------------- | ------------------- | ------------------ | ----- | | message | string | The error message. | 0.0.1 |

GoogleBarcodeScannerModuleInstallProgressEvent

| Prop | Type | Description | Since | | -------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----- | | state | GoogleBarcodeScannerModuleInstallState | The current state of the installation. | 5.1.0 | | progress | number | The progress of the installation in percent between 0 and 100. | 5.1.0 |

Type Aliases

CameraPermissionState

PermissionState | 'limited'

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Enums

BarcodeFormat

| Members | Value | Description | Since | | ---------------- | -------------------------- | ---------------------------------- | ----- | | Aztec | 'AZTEC' | Only available on Android and iOS. | 0.0.1 | | Codabar | 'CODABAR' | Only available on Android and iOS. | 0.0.1 | | Code39 | 'CODE_39' | Only available on Android and iOS. | 0.0.1 | | Code93 | 'CODE_93' | Only available on Android and iOS. | 0.0.1 | | Code128 | 'CODE_128' | Only available on Android and iOS. | 0.0.1 | | DataMatrix | 'DATA_MATRIX' | Only available on Android and iOS. | 0.0.1 | | Ean8 | 'EAN_8' | Only available on Android and iOS. | 0.0.1 | | Ean13 | 'EAN_13' | Only available on Android and iOS. | 0.0.1 | | Itf | 'ITF' | Only available on Android and iOS. | 0.0.1 | | Pdf417 | 'PDF_417' | Only available on Android and iOS. | 0.0.1 | | QrCode | 'QR_CODE' | Only available on Android and iOS. | 0.0.1 | | UpcA | 'UPC_A' | Only available on Android and iOS. | 0.0.1 | | UpcE | 'UPC_E' | Only available on Android and iOS. | 0.0.1 |

LensFacing

| Members | Value | Since | | ----------- | -------------------- | ----- | | Front | 'FRONT' | 0.0.1 | | Back | 'BACK' | 0.0.1 |

BarcodeValueType

| Members | Value | Since | | -------------------- | ------------------------------ | ----- | | CalendarEvent | 'CALENDAR_EVENT' | 0.0.1 | | ContactInfo | 'CONTACT_INFO' | 0.0.1 | | DriversLicense | 'DRIVERS_LICENSE' | 0.0.1 | | Email | 'EMAIL' | 0.0.1 | | Geo | 'GEO' | 0.0.1 | | Isbn | 'ISBN' | 0.0.1 | | Phone | 'PHONE' | 0.0.1 | | Product | 'PRODUCT' | 0.0.1 | | Sms | 'SMS' | 0.0.1 | | Text | 'TEXT' | 0.0.1 | | Url | 'URL' | 0.0.1 | | Wifi | 'WIFI' | 0.0.1 | | Unknown | 'UNKNOWN' | 0.0.1 |

GoogleBarcodeScannerModuleInstallState

| Members | Value | Since | | --------------------- | -------------- | ----- | | UNKNOWN | 0 | 5.1.0 | | PENDING | 1 | 5.1.0 | | DOWNLOADING | 2 | 5.1.0 | | CANCELED | 3 | 5.1.0 | | COMPLETED | 4 | 5.1.0 | | FAILED | 5 | 5.1.0 | | INSTALLING | 6 | 5.1.0 | | DOWNLOAD_PAUSED | 7 | 5.1.0 |

Common Issues

NullPointerException during startScan(...)

The following error may occur when calling the startScan(...) method: Attempt to invoke virtual method 'void androidx.camera.view.PreviewView.setScaleType(androidx.camera.view.PreviewView$ScaleType)' on a null object reference. In this case, make sure that the databinding library is enabled (see Data Binding).

Terms & Privacy

This plugin uses the Google ML Kit:

• Terms & Privacy
• Android Data Disclosure
• iOS Data Disclosure

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [^2]: QR Code is a registered trademark of DENSO WAVE INCORPORATED.