@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

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.

Returns: Promise<ScanDocumentResponse>

Interfaces

ScanDocumentResponse

ScanDocumentOptions

Type Aliases

ResponseType

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

Enums

ScanDocumentResponseStatus

ResponseType

ScannerMode

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