Mobile Document Scanner API Reference

The DocumentScanner class provides a complete document scanning solution that integrates camera access, real-time document boundary detection, manual boundary adjustment, and image perspective correction.

Constructor

DocumentScanner

Create a DocumentScanner instance with settings specified by a DocumentScannerConfig object.

The DocumentScanner class orchestrates three main views:

• DocumentScannerView: Camera interface with document detection and capture modes
• DocumentCorrectionView: Manual boundary adjustment interface
• DocumentResultView: Result preview and action interface

The class supports both single-scan and continuous scanning modes. In continuous mode, the scanner loops back after each successful scan, allowing multiple documents to be captured in sequence.

Syntax

new DocumentScanner(config: DocumentScannerConfig)

Parameters

• config (DocumentScannerConfig) : Configuration settings for the scanner. You must set a valid license key with the license property. See DocumentScannerConfig for a complete description.

Example

HTML:

<div id="myDocumentScannerContainer" style="width: 80vw; height: 80vh;"></div>

JavaScript:

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key
  scannerViewConfig: {
    container: document.getElementById("myDocumentScannerContainer"), // Use this container for the scanner view
  },
});

Example: Continuous Scanning Mode

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  enableContinuousScanning: true,
  onDocumentScanned: async (result) => {
    // Process each scanned document
    await uploadToServer(result.correctedImageResult);
  },
});

await documentScanner.launch();

Methods

launch()

Start the document scanning workflow.

This is the primary method for initiating document scanning. It performs the following:

1. Automatically calls initialize() if not already initialized
2. Opens the camera and displays the DocumentScannerView (unless a file is provided)
3. Guides the user through the configured workflow (scan → correction → result)
4. Returns the final DocumentResult when the workflow completes
5. Automatically calls dispose() to clean up resources

Scanning Modes

• Single-scan mode (default): Captures one document and returns the result
• Continuous scanning mode (enableContinuousScanning): Loops after each scan, invoking onDocumentScanned with each result. The loop continues until the user clicks the close button (X) or stopContinuousScanning() is called. Returns the last scanned result.

File Processing

Passing a File object allows processing an existing image file, bypassing camera input and the DocumentScannerView.

Syntax

async launch(file?: File): Promise<DocumentResult>

Parameters

• file (optional): Image file to process instead of using the camera

Returns

• A Promise resolving to a DocumentResult object, which includes:
  • status: Scan status (success, cancelled, or failed)
  • correctedImageResult: Perspective-corrected document image
  • originalImageResult: Original captured image
  • detectedQuadrilateral: Detected document boundaries

Throws

• Error if a capture session is already in progress

Example: Basic Single-Scan Usage

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
});

const result = await documentScanner.launch();

if (result?.correctedImageResult) {
  resultContainer.innerHTML = "";
  const canvas = result.correctedImageResult.toCanvas();
  resultContainer.appendChild(canvas);
} else {
  resultContainer.innerHTML = "<p>No image scanned. Please try again.</p>";
}

Example: Process an Existing Image File

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
});

const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
const result = await documentScanner.launch(file);

Example: Continuous Scanning Mode

const scannedDocs = [];
const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  enableContinuousScanning: true,
  onDocumentScanned: async (result) => {
    scannedDocs.push(result);
    console.log(`Scanned ${scannedDocs.length} documents`);
  },
});

// This will return the last scanned result when user exits
const lastResult = await documentScanner.launch();

initialize()

This method is called automatically by launch() and typically does not need to be invoked manually.

Initialize the DocumentScanner by setting up Dynamsoft Capture Vision resources and view components.

This method performs the following initialization steps:

1. Validates and processes the configuration provided to the constructor
2. Initializes Dynamsoft Capture Vision engine resources (license, camera, router)
3. Creates and initializes the configured view components (scanner, correction, result)
4. Sets up shared resources and callbacks for communication between views

The method is idempotent - calling it multiple times will return the same resources and components without re-initialization.

Syntax

async initialize(): Promise<{
  resources: SharedResources;
  components: {
    scannerView?: DocumentScannerView;
    correctionView?: DocumentCorrectionView;
    scanResultView?: DocumentResultView;
  };
}>

Returns

• A promise that resolves to an object containing:
  • resources: The SharedResources object containing camera, router, and state
  • components: An object with references to the initialized view components (scannerView, correctionView, scanResultView)

Throws

• Error if initialization fails due to invalid configuration, missing license, or resource loading errors

Example: Manual Initialization (rarely needed)

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
});

try {
  const { resources, components } = await documentScanner.initialize();
  console.log("Scanner initialized successfully");
} catch (error) {
  console.error("Initialization failed:", error);
}

stopContinuousScanning()

Stop continuous scanning and exit the scanning loop.

When called with enableContinuousScanning enabled and launch() running, signal the scanner to stop looping and return from launch() with the last scanned result.

This provides an alternative to using the close button (X) for exiting continuous scanning mode, allowing you to implement custom exit logic based on conditions such as:

• Maximum number of scanned documents reached
• Time limits
• User interaction with custom UI elements
• External events or triggers

Syntax

stopContinuousScanning(): void

Example: Stop After Scanning 5 Documents

let scannedCount = 0;
const scanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  enableContinuousScanning: true,
  onDocumentScanned: async (result) => {
    scannedCount++;
    console.log(`Scanned document ${scannedCount}`);

    if (scannedCount >= 5) {
      scanner.stopContinuousScanning();
    }
  },
});

await scanner.launch(); // Exits after 5 scans

Example: Stop from External Button

const scanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  enableContinuousScanning: true,
  onDocumentScanned: async (result) => {
    // Process each scanned document
    saveDocument(result);
  },
});

// Bind to custom stop button
document.getElementById("stopBtn").addEventListener("click", () => {
  scanner.stopContinuousScanning();
});

await scanner.launch(); // Will exit when stopBtn is clicked

dispose()

This method is called automatically at the end of launch(), so manual invocation is typically only needed if you want to clean up resources before the scanning workflow completes.

Clean up and release all resources used by the DocumentScanner.

This method performs comprehensive cleanup by:

• Disposing all view components (scanner, correction, result)
• Releasing Dynamsoft Capture Vision resources (camera, router)
• Clearing all container elements
• Resetting internal state

After calling dispose, you can create a new DocumentScanner instance if you need to scan again.

Syntax

dispose(): void

Example: Manual Cleanup

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
});

await documentScanner.launch();

// Clean up is automatic after launch completes
// But you can also call it manually if needed:
documentScanner.dispose();
console.log("Scanner resources released");

Configuration Interfaces

DocumentScannerConfig

The DocumentScannerConfig interface passes settings to the DocumentScanner constructor to apply a comprehensive set of UI and business logic customizations.

Only advanced scenarios require editing the UI template or MDS source code. license is the only property required to instantiate a DocumentScanner object. MDS uses sensible default values for all other omitted properties.

Syntax

interface DocumentScannerConfig {
  license?: string;
  container?: HTMLElement | string;
  templateFilePath?: string;
  utilizedTemplateNames?: UtilizedTemplateNames;
  engineResourcePaths?: EngineResourcePaths;
  scannerViewConfig?: DocumentScannerViewConfig;
  resultViewConfig?: DocumentResultViewConfig;
  correctionViewConfig?: DocumentCorrectionViewConfig;
  showResultView?: boolean;
  showCorrectionView?: boolean;
  enableContinuousScanning?: boolean;
  enableFrameVerification?: boolean;
  onDocumentScanned?: (result: DocumentResult) => void | Promise<void>;
  onThumbnailClicked?: (result: DocumentResult) => void | Promise<void>;
  themeColor?: ThemeColor;
  stringConfig?: StringConfig;
}

Properties

Example: Basic Configuration

const config = {
  license: "YOUR_LICENSE_KEY_HERE",
  scannerViewConfig: {
    cameraEnhancerUIPath: "./dist/document-scanner.ui.xml", // Use the local file
  },
  engineResourcePaths: {
    std: "./dist/libs/dynamsoft-capture-vision-std/dist/",
    dip: "./dist/libs/dynamsoft-image-processing/dist/",
    core: "./dist/libs/dynamsoft-core/dist/",
    license: "./dist/libs/dynamsoft-license/dist/",
    cvr: "./dist/libs/dynamsoft-capture-vision-router/dist/",
    ddn: "./dist/libs/dynamsoft-document-normalizer/dist/",
  },
};

Example: Continuous Scanning with Callback

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  enableContinuousScanning: true,
  onDocumentScanned: async (result) => {
    // Process each scanned document
    const canvas = result.correctedImageResult.toCanvas();
    document.getElementById("results").appendChild(canvas);
  },
});

Example: Thumbnail Click Handler

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  enableContinuousScanning: true,
  showCorrectionView: false,
  showResultView: false,
  onThumbnailClicked: async (result) => {
    // Handle thumbnail click event
    console.log("Thumbnail clicked", result);
    // Could open a custom editor, display metadata, etc.
  },
});

DocumentScannerViewConfig

The DocumentScannerViewConfig interface passes settings to the DocumentScanner constructor through the DocumentScannerConfig to apply UI and business logic customizations for the DocumentScannerView.

Simple scenarios do not require editing the UI template or MDS source code. MDS uses sensible default values for all omitted properties.

Syntax

interface DocumentScannerViewConfig {
  container?: HTMLElement | string;
  cameraEnhancerUIPath?: string;
  templateFilePath?: string;
  utilizedTemplateNames?: UtilizedTemplateNames;
  enableBoundsDetectionMode?: boolean;
  enableSmartCaptureMode?: boolean;
  enableAutoCropMode?: boolean;
  enableFrameVerification?: boolean;
  scanRegion?: ScanRegion;
  minVerifiedFramesForAutoCapture?: number;
  showSubfooter?: boolean;
  showPoweredByDynamsoft?: boolean;
}

Properties

Example

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE", // Replace with your actual license key
  scannerViewConfig: {
    cameraEnhancerUIPath: "../dist/document-scanner.ui.xml", // Use the local file
    enableSmartCaptureMode: true, // Enable smart capture by default
    minVerifiedFramesForAutoCapture: 3, // Stricter boundary detection threshold
  },
});

DocumentCorrectionViewConfig

The DocumentCorrectionViewConfig interface passes settings to the DocumentScanner constructor through the DocumentScannerConfig to apply UI and business logic customizations for the DocumentCorrectionView.

Only rare and edge-case scenarios require editing MDS source code. MDS uses sensible default values for all omitted properties.

Syntax

interface DocumentCorrectionViewConfig {
  container?: HTMLElement | string;
  toolbarButtonsConfig?: DocumentCorrectionViewToolbarButtonsConfig;
  templateFilePath?: string;
  utilizedTemplateNames?: UtilizedTemplateNames;
  onFinish?: (result: DocumentResult) => void;
}

Properties

Example

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key
  correctionViewConfig: {
    onFinish: (result) => {
      const canvas = result.correctedImageResult.toCanvas();
      resultContainer.appendChild(canvas);
    },
  },
});

DocumentResultViewConfig

The DocumentResultViewConfig interface passes settings to the DocumentScanner constructor through the DocumentScannerConfig to apply UI and business logic customizations for the DocumentResultView.

Only rare and edge-case scenarios require editing MDS source code. MDS uses sensible default values for all omitted properties.

Syntax

interface DocumentResultViewConfig {
  container?: HTMLElement | string;
  toolbarButtonsConfig?: DocumentResultViewToolbarButtonsConfig;
  onDone?: (result: DocumentResult) => Promise<void>;
  onUpload?: (result: DocumentResult) => Promise<void>;
}

Properties

Example

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key
  resultViewConfig: {
    onDone: async (result) => {
      const canvas = result.correctedImageResult.toCanvas();
      resultContainer.appendChild(canvas);
    },
  },
});

DocumentResult

Represent the output of a scan, including the original image, the corrected image, detected boundaries, and scan status.

Syntax

interface DocumentResult {
  status: ResultStatus;
  correctedImageResult?: DeskewedImageResultItem;
  originalImageResult?: DSImageData;
  detectedQuadrilateral?: Quadrilateral;
}

Properties

ThemeColor

Override the default colors used across all views and the loading screen. Every field is optional; unset fields fall back to the library default. Set it through the themeColor property of DocumentScannerConfig.

Syntax

interface ThemeColor {
  primary?: string;
  toolbarButtonInactive?: string;
  activeIndicator?: string;
  inactiveIndicator?: string;
  correctionQuad?: string;
  backgroundView?: string;
  backgroundToolbar?: string;
  filterMenuBackground?: string;
  filterMenuText?: string;
  scanMoreBackground?: string;
  scanMoreText?: string;
}

Properties

Example

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key
  themeColor: {
    primary: "#0066cc",
    backgroundView: "#1a1a1a",
  },
});

StringConfig

Override the default user-facing strings displayed by the DocumentScanner. Every field is optional; unset fields fall back to the library default. Set it through the stringConfig property of DocumentScannerConfig.

Toolbar button labels (Re-take, Apply, Done, etc.) are not configured here — use the toolbarButtonsConfig of DocumentCorrectionViewConfig and DocumentResultViewConfig for those. Strings that include a {count} or {error} placeholder are noted in their descriptions; the placeholder is substituted at render time.

The resolved string config is process-global: instantiating a new DocumentScanner replaces any previously applied config. Running two scanners with different stringConfig values on the same page is not supported — the most recently constructed scanner wins.

Syntax

interface StringConfig {
  loadingMsg?: string;
  initializingCameraMsg?: string;
  processingImageMsg?: string;
  continuousScanDoneBtn?: string;
  shareTitle?: string;
  downloadFilenamePrefix?: string;
  uploadShareFailedAlert?: string;
  shareErrorAlert?: string;
  selectCameraBtnTitle?: string;
  uploadImageBtnTitle?: string;
  closeScannerBtnTitle?: string;
  cameraSwitcherCameraLabel?: string;
  cameraSwitcherResolutionLabel?: string;
  takePhotoBtnTitle?: string;
  scanMoreBtn?: string;
  filterOriginalBtn?: string;
  filterGrayscaleBtn?: string;
  filterBlackWhiteBtn?: string;
  filterSepiaBtn?: string;
  filterInvertedBtn?: string;
}

Properties

Example

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key
  stringConfig: {
    loadingMsg: "Cargando...",
    continuousScanDoneBtn: "Listo ({count})",
    downloadFilenamePrefix: "invoice",
  },
});

ScanRegion

Set the scan region within the DocumentScannerView viewfinder for document scanning from the DocumentScannerViewConfig.

MDS determines the scan region with the following steps:

1. Use ratio to set the height-to-width ratio of the rectangular scanning region, then scale the rectangle up to fit within the viewfinder.
2. Translate the rectangle upward by the number of pixels specified by regionBottomMargin.
3. Create a visual border for the scanning region boundary on the viewfinder with a given stroke width in pixels and stroke color.

Syntax

interface ScanRegion {
  ratio: {
    width: number;
    height: number;
  };
  regionBottomMargin: number; // Bottom margin calculated in pixels
  style: {
    strokeWidth: number;
    strokeColor: string;
  };
}

Properties

Example

Create a scan region with a height-to-width ratio of 3:2, translated upwards by 20 pixels, with a green, 3 pixel-wide border in the viewfinder:

scanRegion: {
  ratio: {
    width: 2,
    height: 3,
  },
  regionBottomMargin: 20,
  style: {
    strokeWidth: 3,
    strokeColor: "green",
  },
}

Toolbar Button Configurations

ToolbarButtonConfig

A simplified configuration type for toolbar buttons.

This type allows you to customize the appearance and behavior of toolbar buttons by providing a subset of properties from the complete ToolbarButton interface.

Syntax

export type ToolbarButtonConfig = Pick<ToolbarButton, "icon" | "label" | "className" | "isHidden">;

Properties

Example

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE", // Replace this with your actual license key
  correctionViewConfig: {
    toolbarButtonsConfig: {
      fullImage: {
        isHidden: true,
      },
      detectBorders: {
        icon: "path/to/new_icon.png", // Change to the actual path of the new icon
        label: "Custom Label",
      },
    },
  },
});

ToolbarButton

Interface defining the properties and behavior of a toolbar button.

This interface is used internally to create toolbar buttons in the DocumentResultView and DocumentCorrectionView. While developers typically use ToolbarButtonConfig to customize buttons, this interface defines the complete button structure including the click handler. See Configurable Buttons Per Each View for examples.

Syntax

interface ToolbarButton {
  id: string;
  icon: string;
  label: string;
  onClick?: () => void | Promise<void>;
  className?: string;
  isDisabled?: boolean;
  isHidden?: boolean;
}

Properties

Configurable Buttons Per Each View

DocumentCorrectionViewToolbarButtonsConfig

Configuration interface for customizing toolbar buttons in the DocumentCorrectionView.

This interface allows you to customize the appearance and behavior of the toolbar buttons displayed in the DocumentCorrectionView. Each button can be configured using a ToolbarButtonConfig object to modify its icon, label, CSS class, or visibility.

The behaviors described for each button below are the default behaviors. You can override the default behavior by providing a custom onClick handler through the ToolbarButtonConfig.

Syntax

interface DocumentCorrectionViewToolbarButtonsConfig {
  retake?: ToolbarButtonConfig;
  fullImage?: ToolbarButtonConfig;
  detectBorders?: ToolbarButtonConfig;
  apply?: ToolbarButtonConfig;
}

Properties

Example: Customize Button Appearance

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  correctionViewConfig: {
    toolbarButtonsConfig: {
      fullImage: {
        isHidden: true,
      },
      detectBorders: {
        icon: "path/to/new_icon.png",
        label: "Custom Label",
      },
    },
  },
});

Example: Override Button Behavior

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  correctionViewConfig: {
    toolbarButtonsConfig: {
      apply: {
        label: "Confirm",
        onClick: async () => {
          // Custom confirmation logic
          await validateBoundaries();
          console.log("Boundaries confirmed!");
        },
      },
    },
  },
});

DocumentResultViewToolbarButtonsConfig

Configuration interface for customizing toolbar buttons in the DocumentResultView.

This interface allows you to customize the appearance and behavior of the toolbar buttons displayed in the DocumentResultView. Each button can be configured using a ToolbarButtonConfig object to modify its icon, label, CSS class, or visibility.

The behaviors described for each button below are the default behaviors. You can override the default behavior by providing a custom onClick handler through the ToolbarButtonConfig.

Syntax

interface DocumentResultViewToolbarButtonsConfig {
  retake?: ToolbarButtonConfig;
  correct?: ToolbarButtonConfig;
  share?: ToolbarButtonConfig;
  upload?: ToolbarButtonConfig;
  done?: ToolbarButtonConfig;
}

Properties

Example: Customize Button Appearance

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  resultViewConfig: {
    toolbarButtonsConfig: {
      retake: {
        isHidden: true,
      },
      share: {
        icon: "path/to/new_icon.png",
        label: "Custom Label",
      },
    },
  },
});

Example: Override Button Behavior

const documentScanner = new Dynamsoft.DocumentScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  resultViewConfig: {
    toolbarButtonsConfig: {
      done: {
        label: "Save",
        onClick: async () => {
          // Custom save logic
          await saveToServer(documentScanner.result);
          console.log("Document saved!");
        },
      },
      share: {
        onClick: async () => {
          // Custom share logic
          await sendViaEmail(documentScanner.result);
        },
      },
    },
  },
});

Assisting Interfaces

UtilizedTemplateNames

Capture Vision template names for document detection and normalization.

You may set custom names to self-host resources or fully self-host MDS. See self-hosting resources and DCV templates for details.

Syntax

interface UtilizedTemplateNames {
  detect: string;
  normalize: string;
}

Default Value

{
  detect: "DetectDocumentBoundaries_Default",
  normalize: "NormalizeDocument_Default"
}

ResultStatus

Represents the status of a document scanning operation.

Syntax

type ResultStatus = {
  code: EnumResultStatus;
  message?: string;
};

Properties

EnumResultStatus

Enumeration of possible result status codes.

Syntax

enum EnumResultStatus {
  RS_SUCCESS = 0,
  RS_CANCELLED = 1,
  RS_FAILED = 2,
}

Values

EngineResourcePaths

Paths to extra resources such as .wasm engine files. The default paths point to CDNs and so may be left unset. You may set custom paths to self-host resources, or host MDS fully offline - see self-hosting resources for details.

Syntax

interface EngineResourcePaths {
  rootDirectory?: string;
  std?: string | PathInfo;
  dip?: string | PathInfo;
  dnn?: string | PathInfo;
  core?: string | PathInfo;
  license?: string | PathInfo;
  cvr?: string | PathInfo;
  utility?: string | PathInfo;
  dbr?: string | PathInfo;
  dlr?: string | PathInfo;
  ddn?: string | PathInfo;
  dcp?: string | PathInfo;
  dce?: string | PathInfo;
  dlrData?: string | PathInfo;
  ddv?: string | PathInfo;
  dwt?: string | DwtInfo;
}