@capgo/capacitor-document-scanner

Scan paper documents with the native scanner UI: VisionKit on iOS and Google ML Kit on Android find the page edges, fix the perspective and return clean images. Add receipt, ID or contract capture to your app without building a camera screen.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-document-scanner in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-document-scanner to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Native scanner UI: scanDocument() opens the VisionKit document camera on iOS and the ML Kit document scanner on Android, with automatic edge detection and perspective correction.
• Multi-page scans: capture up to 24 pages in one session, or pass maxNumDocuments: 1 for single-page mode. Android stops after that page. On iOS the camera stops only when iosVisionKitSwizzle is enabled; the default binary drops the extra pages after Save.
• Crop and review: Android always offers crop and rotate. On iOS, VisionKit shows its review screen before Save. Forcing the editor after every capture is an opt-in swizzle. See iOS App Store review.
• Image cleanup: tune brightness and contrast on both platforms. On Android, scannerMode adds filters and ML cleaning that removes stains and fingers.
• Flexible output: get file paths or base64 strings with responseType, plus a success or cancel status.
• Platforms: iOS and Android. Web is not supported: scanDocument() rejects as unimplemented.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/document-scanner/

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

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

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-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 @capgo/capacitor-document-scanner
npx cap sync

Important Notes

Android Emulator Limitations

The ML Kit Document Scanner does not work on Android emulators. This is a limitation of Google Play Services and ML Kit on emulated devices. When testing your app:

• ✅ Use a physical Android device for testing document scanning
• ❌ Android emulators will show an error: "Document scanner is not supported on Android emulators"

This limitation is due to:

• Google Play Services compatibility issues with emulator environments
• ML Kit Document Scanner requiring actual hardware camera capabilities
• Emulators lacking the necessary ML Kit runtime components

For development and testing, always use a real Android device.

iOS App Store review and the VisionKit swizzle

The default iOS binary does not include the private VisionKit swizzle. Those calls load VNDocumentCameraViewController_InProcess with NSClassFromString and exchange documentCameraController:canAddImages: through method_exchangeImplementations. The same code reads private UIKit gesture state so it can open the crop editor. The iPhoneOS 27.1 SDK still has no public page-limit or per-capture callback on VNDocumentCameraViewController.

This follows @capgo/capacitor-social-login: the swizzle stays out of the build unless the app opts in.

With the default build:

• Scanning uses the public VNDocumentCameraViewController API.
• maxNumDocuments trims the pages returned after Save. The camera can still capture up to VisionKit's 24-page system limit.
• letUserAdjustCrop and reviewCapturedDocument do not force the editor after each capture. VisionKit's own review screen before Save is unchanged.
• Android behavior is unchanged.

Enable the swizzle when you need that iOS behavior back:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    DocumentScanner: {
      iosVisionKitSwizzle: true,
    },
  },
};

export default config;

Then run bunx cap sync. That command writes the flag into Package.swift and CapgoCapacitorDocumentScanner.podspec in the installed plugin, and the next iOS build compiles CAPGO_DOCUMENT_SCANNER_VISIONKIT_SWIZZLE. Remove the flag and run bunx cap sync again to ship the default binary.

With the swizzle compiled in:

• maxNumDocuments stops the camera when the limit is reached. VisionKit's own cap is still 24.
• letUserAdjustCrop opens the VisionKit editor after each capture.
• reviewCapturedDocument shows the current page before the next capture, and the editor still opens when the limit is reached.
• The binary contains method_exchangeImplementations, the private class lookup, and the private gesture reads. Android is unchanged.

That can make App Store review harder. Static analysis may name method_exchangeImplementations. You can still explain the use in the review notes: the swizzle only caps the page count and opens the editor inside Apple's document scanner. It does not read private user data, and it does not change anything outside that screen. Some submissions get a question and are approved after that explanation. Others go through with no mention of the symbol. Approval is per submission, so a previous pass does not decide the next binary.

Demo

Scanning one note

| iOS | Android | |:---:|:-------:| | | |

API

• scanDocument(...)
• Interfaces
• Type Aliases
• Enums

scanDocument(...)

scanDocument(options?: ScanDocumentOptions | undefined) => Promise<ScanDocumentResponse>

Opens the device camera and starts the document scanning experience.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | ScanDocumentOptions |

Returns: Promise<ScanDocumentResponse>

Interfaces

ScanDocumentResponse

| Prop | Type | Description | | ------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------ | | scannedImages | string[] | Scanned images in the requested response format. | | status | ScanDocumentResponseStatus | Indicates whether the scan completed or was cancelled. |

| Method | Signature | Description | | -------------------- | -------------------------------------------- | --------------------------------------- | | getPluginVersion | () => Promise<{ version: string; }> | Get the native Capacitor plugin version |

ScanDocumentOptions

| Prop | Type | Description | Default | | ---------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- | | croppedImageQuality | number | Android only: quality of the cropped image from 0 - 100 (100 is best). | 100 | | letUserAdjustCrop | boolean | Allow the user to adjust the detected crop before saving. On iOS, VisionKit already shows its own review screen before Save. Forcing that editor after every capture needs the private VisionKit swizzle, which is not compiled into the default binary. Set plugins.DocumentScanner.iosVisionKitSwizzle to true and run bunx cap sync to include it. See the README. On Android, crop/rotate is always part of the ML Kit UI in every ScannerMode; use scannerMode to control filters and ML cleaning instead. | true | | reviewCapturedDocument | boolean | When enabled, shows the current scanned page before continuing so the user can review it and explicitly continue or finish the flow. On iOS this forces the native VisionKit preview/editor between captures only when plugins.DocumentScanner.iosVisionKitSwizzle is compiled in. The default binary leaves the system review screen before Save unchanged. On Android this switches to a one-page-at-a-time flow between ML Kit sessions. With the iOS swizzle enabled, the review/editor screen is still shown when the scan limit is reached. | false | | maxNumDocuments | number | Maximum number of documents to scan. On iOS the default binary uses public VisionKit and trims the returned pages to this limit after Save. VisionKit itself still allows up to 24 captures. Stopping the camera at a lower limit requires plugins.DocumentScanner.iosVisionKitSwizzle. On Android: customizable limit; defaults to 20 for performance (clamped 1-24). Set to 1 for single-scan mode. Android stops after one document. On iOS the camera stops after one document only when plugins.DocumentScanner.iosVisionKitSwizzle is compiled in. | 20 on Android, 24 on iOS | | responseType | ResponseType | Format to return scanned images in (file paths or base64 strings). | ResponseType.ImageFilePath | | brightness | number | Brightness adjustment applied to scanned images. Range: -255 to 255 (0 = no change, positive = brighter, negative = darker) Useful for compensating low-light scans. | 0 | | contrast | number | Contrast adjustment applied to scanned images. Range: 0.0 to 10.0 (1.0 = no change, >1 = more contrast, <1 = less contrast) Helps improve text clarity in poorly lit scans. | 1.0 | | scannerMode | ScannerMode | Android only: scanner mode that controls ML Kit features and filters. Independent of letUserAdjustCrop (crop/rotate is available in all modes). - 'base': Basic scan with crop/rotate, no filters or ML cleaning - 'base_with_filter': Adds grayscale and auto-enhancement filters - 'full': All features including ML-based image cleaning (erases stains, fingers, etc.) | ScannerMode.Full |

Type Aliases

ResponseType

'basic' | 'cors' | 'default' | 'error' | 'opaque' | 'opaqueredirect'

Enums

ScanDocumentResponseStatus

| Members | Value | Description | | ------------- | ---------------------- | --------------------------------- | | Success | 'success' | The scan completed successfully. | | Cancel | 'cancel' | The user cancelled the scan flow. |

ResponseType

| Members | Value | Description | | ------------------- | ---------------------------- | ------------------------------------------------ | | Base64 | 'base64' | Return scanned images as base64-encoded strings. | | ImageFilePath | 'imageFilePath' | Return scanned images as file paths on disk. |

ScannerMode

| Members | Value | Description | | -------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Base | 'base' | Basic document scanning with crop and rotate features only. No filters or ML-based enhancements. | | BaseWithFilter | 'base_with_filter' | Basic features plus automatic filters (grayscale, auto-enhancement). | | Full | 'full' | Full feature set including ML-based image cleaning. Automatically removes stains, fingers, and other artifacts. |

credits

This plugin is a re implementation of the original https://document-scanner.js.org Thanks for the original work, we recoded it with more modern SDK but explodes the same API