--- title: Capacitor ML Kit Document Scanner Plugin description: Unofficial Capacitor plugin for Google ML Kit Document Scanner SDK to scan documents. With support for Android and iOS. tags: - Android - iOS search: boost: 2 faq: true github_repo: capawesome-team/capacitor-mlkit npm_package: "@capacitor-mlkit/document-scanner" --- # Capacitor ML Kit Document Scanner Plugin Unofficial Capacitor plugin for [ML Kit Document Scanner](https://developers.google.com/ml-kit/vision/doc-scanner).[^1]
Deliver Live Updates to your Capacitor app with Capawesome Cloud
## 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 | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | >=8.x.x | Active support | ## Installation You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: ```bash 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: ```bash 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: ```typescript 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); }; ``` ### 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: ```typescript 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(...)`](#scandocument) * [`isGoogleDocumentScannerModuleAvailable()`](#isgoogledocumentscannermoduleavailable) * [`installGoogleDocumentScannerModule()`](#installgoogledocumentscannermodule) * [`addListener('googleDocumentScannerModuleInstallProgress', ...)`](#addlistenergoogledocumentscannermoduleinstallprogress-) * [`removeAllListeners()`](#removealllisteners) * [Interfaces](#interfaces) * [Enums](#enums) ### scanDocument(...) ```typescript scanDocument(options: ScanOptions) => Promise ``` Starts the document scanning process. Only available on Android. | Param | Type | | ------------- | --------------------------------------------------- | | **`options`** | ScanOptions | **Returns:** Promise<ScanResult> **Since:** 7.3.0 -------------------- ### isGoogleDocumentScannerModuleAvailable() ```typescript isGoogleDocumentScannerModuleAvailable() => Promise ``` 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() ```typescript installGoogleDocumentScannerModule() => Promise ``` 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', ...) ```typescript addListener(eventName: 'googleDocumentScannerModuleInstallProgress', listenerFunc: (event: GoogleDocumentScannerModuleInstallProgressEvent) => void) => Promise ``` Called when the Google Document Scanner module is installed. Only available on Android. | Param | Type | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **`eventName`** | 'googleDocumentScannerModuleInstallProgress' | | **`listenerFunc`** | (event: GoogleDocumentScannerModuleInstallProgressEvent) => void | **Returns:** Promise<PluginListenerHandle> **Since:** 7.3.0 -------------------- ### removeAllListeners() ```typescript removeAllListeners() => Promise ``` Remove all listeners for this plugin. Only available on Android. **Since:** 7.3.0 -------------------- ### Interfaces #### ScanResult Result of a document scan operation. | Prop | Type | Description | Since | | ------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----- | | **`scannedImages`** | string[] | An array of URIs for the scanned image pages (JPEG). Present if 'JPEG' or 'JPEG_PDF' was requested in resultFormats. | 7.3.0 | | **`pdf`** | PdfInfo | Information about the generated PDF. Present if 'PDF' or 'JPEG_PDF' was requested in resultFormats. | 7.3.0 | #### PdfInfo | Prop | Type | Description | Since | | --------------- | ------------------- | ---------------------------------- | ----- | | **`uri`** | string | The URI of the generated PDF file. | 7.3.0 | | **`pageCount`** | number | The number of pages in the PDF. | 7.3.0 | #### ScanOptions | Prop | Type | Description | Default | Since | | -------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----- | | **`galleryImportAllowed`** | boolean | Whether to allow importing from the photo gallery. | false | 7.3.0 | | **`pageLimit`** | number | The maximum number of pages that can be scanned. | 10 | 7.3.0 | | **`resultFormats`** | 'JPEG' \| 'PDF' \| 'JPEG_PDF' | The desired result formats. Can be 'JPEG', 'PDF', or 'JPEG_PDF'. | 'JPEG_PDF' | 7.3.0 | | **`scannerMode`** | 'FULL' \| 'BASE' \| 'BASE_WITH_FILTER' | The scanner mode. BASE: Basic editing capabilities (crop, rotate, reorder pages, etc.). BASE_WITH_FILTER: Adds image filters (grayscale, auto image enhancement, etc.) to the BASE mode. FULL: Adds ML-enabled image cleaning capabilities (erase stains, fingers, etc.) to the BASE_WITH_FILTER mode. This mode will also allow future major features to be automatically added along with Google Play services updates, while the other two modes will maintain their current feature sets and only receive minor refinements. | "FULL" | 7.3.0 | #### IsGoogleDocumentScannerModuleAvailableResult | Prop | Type | Description | Since | | --------------- | -------------------- | --------------------------------------------------------------- | ----- | | **`available`** | boolean | Whether or not the Google Document Scanner module is available. | 7.3.0 | #### PluginListenerHandle | Prop | Type | | ------------ | ----------------------------------------- | | **`remove`** | () => Promise<void> | #### GoogleDocumentScannerModuleInstallProgressEvent | Prop | Type | Description | Since | | -------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----- | | **`state`** | GoogleDocumentScannerModuleInstallState | The current state of the installation. | 7.3.0 | | **`progress`** | number | The progress of the installation in percent between 0 and 100. | 7.3.0 | ### Enums #### GoogleDocumentScannerModuleInstallState | Members | Value | Since | | --------------------- | -------------- | ----- | | **`UNKNOWN`** | 0 | 7.3.0 | | **`PENDING`** | 1 | 7.3.0 | | **`DOWNLOADING`** | 2 | 7.3.0 | | **`CANCELED`** | 3 | 7.3.0 | | **`COMPLETED`** | 4 | 7.3.0 | | **`FAILED`** | 5 | 7.3.0 | | **`INSTALLING`** | 6 | 7.3.0 | | **`DOWNLOAD_PAUSED`** | 7 | 7.3.0 | ## 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](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/): Scan barcodes and QR codes with ML Kit Barcode Scanning. - [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/): Display PDF documents in a fullscreen native viewer. - [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a scanned file with the default application. ## Terms & Privacy This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit): - [Terms & Privacy](https://developers.google.com/ml-kit/terms) - [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure) - [iOS Data Disclosure](https://developers.google.com/ml-kit/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](https://cloud.capawesome.io/newsletter/). ## Changelog See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/document-scanner/CHANGELOG.md). ## License See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/document-scanner/LICENSE). [^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.