Capacitor ML Kit Document Scanner Plugin

Unofficial Capacitor plugin for ML Kit Document Scanner.[^1]

Use Cases

The Document Scanner plugin is typically used whenever an app needs to digitize paper documents with the camera, for example:

• Receipt and expense capture: Let users scan receipts and invoices as JPEG images or PDF files for expense tracking.
• Document archiving: Digitize contracts, letters, and other paperwork into multi-page PDF documents.
• Form submission: Let users scan and submit signed forms or supporting documents in your app.
• Clean document photos: Use the ML-enabled image cleaning capabilities to remove stains and fingers from scanned pages.

Compatibility

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/document-scanner` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capacitor-mlkit/document-scanner
npx cap sync

Android

Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

• $mlkitDocumentScannerVersion version of com.google.android.gms:play-services-mlkit-document-scanner (default: 16.0.0)

This can be useful if you encounter dependency conflicts with other plugins in your project.

Usage

The following examples show how to scan a document and how to check and install the Google Document Scanner module.

Scan a document

Start the document scanning process, which opens the ML Kit Document Scanner UI. You can allow gallery imports, limit the number of pages, and choose the result formats and scanner mode. Only available on Android:

import { DocumentScanner } from '@capacitor-mlkit/document-scanner';

const scanDocument = async () => {
  const result = await DocumentScanner.scanDocument({
    galleryImportAllowed: true,
    pageLimit: 5,
    resultFormats: 'JPEG_PDF',
    scannerMode: 'FULL',
  });

  console.log('Scanned images:', result.scannedImages);
  console.log('PDF info:', result.pdf);
};

On Android, the system may destroy the app while the scanner is open. In this case, the promise will never resolve. Instead, the result is delivered through the appRestoredResult event of the App plugin when the app is restored:

import { App } from '@capacitor/app';

App.addListener('appRestoredResult', event => {
  if (event.pluginId !== 'DocumentScanner' || event.methodName !== 'scanDocument') {
    return;
  }
  if (event.success) {
    const scannedImages = event.data.scannedImages;
  } else {
    console.error(event.error?.message);
  }
});

Check and install the Google Document Scanner module

The document scanner models, scanning logic, and UI flow are dynamically downloaded by Google Play services. Check if the module is available and install it if needed. The installation only starts with this call; the googleDocumentScannerModuleInstallProgress event notifies you about the progress. Only available on Android:

import { DocumentScanner } from '@capacitor-mlkit/document-scanner';

const isGoogleDocumentScannerModuleAvailable = async () => {
  const result = await DocumentScanner.isGoogleDocumentScannerModuleAvailable();
  console.log('Is Google Document Scanner module available:', result.available);
};

const installGoogleDocumentScannerModule = async () => {
  await DocumentScanner.installGoogleDocumentScannerModule();
  console.log('Google Document Scanner module installation started.');
};

DocumentScanner.addListener('googleDocumentScannerModuleInstallProgress', (event) => {
  console.log('Installation progress:', event.progress, '%');
  console.log('Current state:', event.state);
});

API

• scanDocument(...)
• isGoogleDocumentScannerModuleAvailable()
• installGoogleDocumentScannerModule()
• addListener('googleDocumentScannerModuleInstallProgress', ...)
• removeAllListeners()
• Interfaces
• Enums

scanDocument(...)

scanDocument(options: ScanOptions) => Promise<ScanResult>

Starts the document scanning process.

Attention: On Android, the system may destroy the app while the scanner is open. In this case, the promise will never resolve. Instead, the result is delivered through the appRestoredResult event of the App plugin when the app is restored.

Only available on Android.

Returns: Promise<ScanResult>

Since: 7.3.0

isGoogleDocumentScannerModuleAvailable()

isGoogleDocumentScannerModuleAvailable() => Promise<IsGoogleDocumentScannerModuleAvailableResult>

Check if the Google Document Scanner module is available.

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

Only available on Android.

Returns: Promise<IsGoogleDocumentScannerModuleAvailableResult>

Since: 7.3.0

installGoogleDocumentScannerModule()

installGoogleDocumentScannerModule() => Promise<void>

Install the Google Document Scanner module.

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

Only available on Android.

Since: 7.3.0

addListener('googleDocumentScannerModuleInstallProgress', ...)

addListener(eventName: 'googleDocumentScannerModuleInstallProgress', listenerFunc: (event: GoogleDocumentScannerModuleInstallProgressEvent) => void) => Promise<PluginListenerHandle>

Called when the Google Document Scanner module is installed.

Only available on Android.

Returns: Promise<PluginListenerHandle>

Since: 7.3.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Only available on Android.

Since: 7.3.0

Interfaces

ScanResult

Result of a document scan operation.

PdfInfo

ScanOptions

IsGoogleDocumentScannerModuleAvailableResult

PluginListenerHandle

GoogleDocumentScannerModuleInstallProgressEvent

Enums

GoogleDocumentScannerModuleInstallState

Notes

• The ML Kit Document Scanner models, scanning logic, and UI flow are dynamically downloaded by Google Play services. Users might have to wait for these to download before the first use. You can use the isGoogleDocumentScannerModuleAvailable and installGoogleDocumentScannerModule methods to check for and install the module, and listen to the googleDocumentScannerModuleInstallProgress event for progress updates.
• This API requires Android API level 21 or above.
• It also requires a minimal device total RAM of 1.7GB. If lower, it returns an MlKitException with error code UNSUPPORTED when calling the API (this plugin will reject the promise).
• Consider that generating document files takes time and requires processing power, so only request the output formats (JPEG, or PDF, or both) you actually need via the resultFormats option.

FAQ

Which platforms are supported by this plugin?

The plugin is only available on Android, since the underlying ML Kit Document Scanner is provided by Google Play services. All methods reject on other platforms.

Why is the document scanner not available on first use?

The ML Kit Document Scanner models, scanning logic, and UI flow are dynamically downloaded by Google Play services, so users might have to wait for the download before the first use. Use isGoogleDocumentScannerModuleAvailable() to check for the module, installGoogleDocumentScannerModule() to install it, and listen to the googleDocumentScannerModuleInstallProgress event for progress updates.

Which result formats can I get from a scan?

You can request JPEG images, a PDF file, or both via the resultFormats option. The result then contains an array of URIs for the scanned image pages and/or information about the generated PDF, including its URI and page count. Since generating document files takes time and processing power, only request the formats you actually need.

What is the difference between the scanner modes?

The BASE mode provides basic editing capabilities such as crop, rotate, and reorder pages. The BASE_WITH_FILTER mode adds image filters such as grayscale and auto image enhancement. The FULL mode (the default) additionally provides ML-enabled image cleaning capabilities, for example erasing stains and fingers, and will automatically receive future major features along with Google Play services updates.

Are there any device requirements?

Yes, the API requires Android API level 21 or above and a minimal device total RAM of 1.7 GB. On devices with less RAM, the API returns an MlKitException with error code UNSUPPORTED and the plugin rejects the promise.

Can users import existing photos instead of scanning?

Yes, set the galleryImportAllowed option to true to allow importing pages from the photo gallery. It is disabled by default.

Related Plugins

• ML Kit Barcode Scanning: Scan barcodes and QR codes with ML Kit Barcode Scanning.
• PDF Viewer: Display PDF documents in a fullscreen native viewer.
• File Opener: Open a scanned file with the default application.

Terms & Privacy

This plugin uses the Google ML Kit:

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

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

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.